[db] Add trace context propagation for MongoDB via the `comment` field

[hossain-rayhan]

Area(s)

area:db

What's missing?

docs/db/mongodb.md currently defines Spans and Metrics but has no
Context propagation section, unlike the other databases that gained one under
#2162 and the framework in #2495:

• SQL Server — SET CONTEXT_INFO
• Oracle — V$SESSION.ACTION
• PostgreSQL — SET application_name ([db] Add context propagation for PostgreSQL via SET application_name #3581)
• MySQL — SET @traceparent ([db] Add context propagation for MySQL via SET @traceparent #3768)

As a result there is no standard, cross-language way for a client to propagate
W3C trace context to the server, so application spans and server-side spans
appear as two disconnected traces. In #2162, @XSAM noted follow-up issues may be
opened for specific databases; this is the MongoDB follow-up.

Because the instrumentation lives in the MongoDB drivers, this convention
would apply not only to MongoDB itself but to any database accessed through the
MongoDB drivers / MongoDB wire protocol (for example, DocumentDB and other
MongoDB-compatible engines). A single carrier convention therefore benefits the
whole MongoDB-driver ecosystem rather than one implementation.

Describe the solution you'd like

Add a Context propagation section to docs/db/mongodb.md that standardizes
carrying W3C trace context in the MongoDB comment command field, mirroring
the existing per-database sections.

Proposed shape (opt-in, not enabled by default, consistent with SQL Server /
Oracle / PostgreSQL / MySQL):

• Carrier: the top-level comment command field, set to a JSON/BSON object.
• Detection: the comment is treated as trace context iff it is an
  object containing a top-level traceparent; a plain-string comment or an
  object without traceparent is left untouched.
• Fields: traceparent (required, W3C, version 00), tracestate
  (optional, carried opaquely), and an optional slot for the user's own comment
  so it remains recoverable.
• Failure handling: any malformed/absent/unsupported value is ignored and a
  fresh trace is started; propagation never breaks the operation.

Why the comment field (and how it differs from SQL-comment propagation)

Concerns raised in open-telemetry/opentelemetry-specification#2279 and
google/sqlcommenter#284 were about embedding context in SQL statement text:
mutating the statement string changes its identity. The MongoDB comment field
differs in two ways that matter at the wire-protocol layer:

1. The context travels in a dedicated, structured field of the command,
   separate from the operation and query, rather than being appended to
   statement text, so the convention does not require mutating any
   query/operation text. We propose the convention specify only this
   wire-protocol carrier and leave how a server propagates the context further to
   the implementation, consistent with how the existing per-database sections
   document a carrier without dictating downstream handling.
2. The comment field is bounded by maxBsonObjectSize rather than a small
   fixed byte limit, so unlike CONTEXT_INFO (128 B) / V$SESSION.ACTION
   (64 B) it can carry tracestate in addition to traceparent.

Prior art / consistency

• Framework: Add SQL commenter as context propagation for databases #2495; umbrella: [Database] Enable trace context propagation between application and database via instrumentation libraries #2162.
• Existing sections: SQL Server, Oracle, PostgreSQL ([db] Add context propagation for PostgreSQL via SET application_name #3581), MySQL ([db] Add context propagation for MySQL via SET @traceparent #3768).
• W3C Trace Context: https://www.w3.org/TR/trace-context/
• A working reference implementation of the client → server (wire protocol) hop
  already exists in a MongoDB-compatible gateway (DocumentDB); it extracts a
  traceparent (and carries tracestate opaquely) from the comment field and
  re-parents the server's root span. We can contribute conformance test vectors.

Additional context

Because context injection would happen in the MongoDB driver / instrumentation
layer, MongoDB and MongoDB-compatible databases (e.g. DocumentDB) would all
benefit from the same convention without per-engine work.

We would like to bring this to a Semantic Conventions DB SIG meeting to align on
the field shape (flat W3C keys vs. a reserved namespace) and status. We are
willing to write the specification PR.

Tip

_{React with 👍 to help prioritize this issue. Please use comments to provide useful context, avoiding +1 or me too, to help us triage it. Learn more here.}