DRIVERS-3454 Support trace context propagation to the server

source/message/OP_MSG.md

@@ -53,6 +53,7 @@ struct Section {
             cstring    identifier;
             document*  documents;
         };
+        document telemetry; // payloadType == 3
     };
 };
 
@@ -74,6 +75,16 @@ Each `OP_MSG` MUST NOT exceed the `maxMessageSizeBytes` as configured by the Mon
 Each `OP_MSG` MUST have one section with `Payload Type 0`, and zero or more `Payload Type 1`. Bulk writes SHOULD use
 `Payload Type 1`, and MUST do so when the batch contains more than one entry.
 
+Each `OP_MSG` request MAY additionally contain **at most one** section with `Payload Type 3`, carrying telemetry
+context. `Payload Type 3` is request-only: drivers MAY send it, and it MUST NOT appear in server replies. Its payload is
+a single BSON document whose contents are defined by the
+[OpenTelemetry specification](../open-telemetry/open-telemetry.md). Servers and intermediaries that do not recognize a
+section kind fail the message (see below), so senders MUST gate emission of this section on server support as defined by
+the OpenTelemetry specification.
+
+Note: `Payload Type 2` is reserved for server-internal use (a security-token section populated by the server and
+infrastructure components, never by drivers), so the next payload type available for driver-emitted content is 3.
+
 Sections may exist in any order. Each `OP_MSG` MAY contain a checksum, and MUST set the relevant `flagBits` when that
 field is included.
 
@@ -157,13 +168,13 @@ MongoDB server only handles the `exhaustAllowed` bit on the following operations
 ##### sections
 
 Each message contains one or more sections. A section is composed of an uint8 which determines the payload's type, and a
-separate payload field. The payload size for payload type 0 and 1 is determined by the first 4 bytes of the payload
+separate payload field. The payload size for payload type 0, 1, and 3 is determined by the first 4 bytes of the payload
 field (includes the 4 bytes holding the size but not the payload type).
 
-| Field   | Description                                                                       |
-| ------- | --------------------------------------------------------------------------------- |
-| type    | A byte indicating the layout and semantics of payload                             |
-| payload | The payload of a section can either be a single document, or a document sequence. |
+| Field   | Description                                                                                                               |
+| ------- | ------------------------------------------------------------------------------------------------------------------------- |
+| type    | A byte indicating the layout and semantics of payload                                                                     |
+| payload | The payload of a section can either be a single document (Payload Type 0 and 3), or a document sequence (Payload Type 1). |
 
 When the Payload Type is 0, the content of the payload is:
 
@@ -179,11 +190,17 @@ When the Payload Type is 1, the content of the payload is:
 | identifier | A unique identifier (for this message). Generally the name of the "command argument" it contains the value for |
 | documents  | 0 or more BSON documents. Each BSON document cannot be larger than `maxBSONObjectSize`.                        |
 
+When the Payload Type is 3, the content of the payload is:
+
+| Field    | Description                                                                                                                                                                                                                                                                                                                                                                                                                                                        |
+| -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| document | A single BSON document containing telemetry context, as defined by the [OpenTelemetry specification](../open-telemetry/open-telemetry.md). The payload size is inferred from the document's leading int32. Servers enforce a maximum size for this section (4096 bytes as of MongoDB 9.0, see [`kMaxTelemetrySectionSize`](https://github.com/mongodb/mongo/blob/master/src/mongo/rpc/op_msg.cpp#L65-L69)) and reject messages whose telemetry section exceeds it. |
+
 Any unknown Payload Types MUST result in an error and the socket MUST be closed. There is no ordering implied by payload
 types. A section with payload type 1 can be serialized before payload type 0.
 
-A fully constructed `OP_MSG` MUST contain exactly one `Payload Type 0`, and optionally any number of `Payload Type 1`
-where each identifier MUST be unique per message.
+A fully constructed `OP_MSG` MUST contain exactly one `Payload Type 0`, optionally any number of `Payload Type 1` where
+each identifier MUST be unique per message, and optionally at most one `Payload Type 3`.
 
 #### Command Arguments As Payload
 
@@ -405,6 +422,7 @@ In the near future, this opcode is expected to be extended and include support f
 
 ### Changelog
 
+- 2026-07-21: Add `Payload Type 3` (telemetry context BSON document; DRIVERS-3454).
 - 2026-06-05: Use OP_MSG for all messages.
 - 2024-04-30: Convert from RestructuredText to Markdown.
 - 2022-10-05: Remove spec front matter.

source/open-telemetry/open-telemetry.md

@@ -322,6 +322,40 @@ available:
 - `exception.type`
 - `exception.stacktrace`
 
+#### Propagating Trace Context to the Server
+
+Drivers MUST propagate the active trace context to servers that support it, so that server-generated spans join the same
+distributed trace as the driver's spans.
+
+The trace context is carried in an `OP_MSG` section with [`Payload Type 3`](../message/OP_MSG.md), whose payload is a
+single BSON document with the following schema:
+
+```json
+{ "otel": { "traceparent": "<string>" } }
+```
+
+`traceparent` is the [W3C traceparent](https://www.w3.org/TR/trace-context/#traceparent-header) value of the **command
+span**: the propagated context MUST be that of the command span for the command being sent, so server spans join the
+trace as children of the exact command (and retry attempt) that produced them.
+
+Drivers MUST attach the section to a command if and only if all of the following hold:
+
+1. Tracing is enabled for the `MongoClient` (see
+    [Enabling, Disabling, and Configuring OpenTelemetry](#enabling-disabling-and-configuring-opentelemetry)).
+2. The connection's `maxWireVersion` is greater than or equal to 29 (MongoDB 9.0).
+3. A valid `traceparent` value is available from the command span for the command being sent.
+
+A `traceparent` value is valid if and only if it is exactly 55 characters of the form
+`00-<32 lowercase hex>-<16 lowercase hex>-<2 lowercase hex flags>` and neither the trace-id nor the parent-id is all
+zeroes. This mirrors the server-side validation. If no valid value is available, drivers MUST omit the section entirely
+rather than send an invalid or truncated value. Drivers MUST NOT append a `tracestate` suffix. Drivers MUST propagate
+unsampled trace contexts (trace-flags `00`); the sampling decision MUST NOT affect whether the section is attached.
+
+A message MUST NOT contain more than one telemetry section. Commands that carry no command span (for example server
+monitoring, authentication, and security-sensitive commands) naturally send no section.
+
+No tracing data is returned in server responses as part of this feature.
+
 ## Motivation for Change
 
 A common complaint from our support team is that they don't know how to easily get debugging information from drivers.
@@ -423,8 +457,21 @@ Further, we already have two attributes that configure tracing, and we expect th
 
 A URI options can be added later if we realise our users need it, while the opposite is not easily accomplished.
 
+### Wire protocol version gate instead of a hello capability
+
+An alternative was for servers to advertise support via a `hello` response field. Gating on `maxWireVersion` was chosen
+instead: the wire protocol version acts as the schema contract for the telemetry payload, so drivers know exactly which
+fields a server accepts, and any future payload additions require a wire version bump rather than a second, parallel
+negotiation mechanism.
+
+### BSON document instead of a bare traceparent string
+
+Carrying the traceparent inside a BSON document allows future propagation fields to be added to the same section without
+redesigning the payload format.
+
 ## Changelog
 
+- 2026-07-21: Add trace context propagation to the server via the `OP_MSG` telemetry section (DRIVERS-3454).
 - 2026-06-16: Clarified that the `db.query.text` attribute should be serialized to Relaxed Extended JSON.
 - 2026-02-09: Renamed `db.system` to `db.system.name` according to the corresponding update of OpenTelemetry semantic
     conventions.

source/wireversion-featurelist/wireversion-featurelist.md

@@ -23,6 +23,7 @@
 | 7.2            | 23           | <p>Database Validation on `mongos` Aggregation Queries</p><p>`serverStatus` Metrics</p><p>Default Chunks Per Shard</p>                                                                                                                                                      |
 | 7.3            | 24           | <p>Compaction Improvements</p><p>New `serverStatus` metrics</p>                                                                                                                                                                                                             |
 | 8.0            | 25           | <p>Range Encryption GA</p><p>OIDC authentication mechanism</p><p>New `bulkWrite` command</p><p>`snapshot` read concern on capped collections</p>                                                                                                                            |
+| 9.0            | 29           | <p>`OP_MSG` telemetry section (`Payload Type 3`, OpenTelemetry trace context propagation)</p>                                                                                                                                                                               |
 
 In server versions 5.0 and earlier, the wire version was defined as a numeric literal in
 [src/mongo/db/wire_version.h](https://github.com/mongodb/mongo/blob/master/src/mongo/db/wire_version.h). Since server