JAVA-6222 Support trace context propagation to the server by nhachicha · Pull Request #2022 · mongodb/mongo-java-driver

nhachicha · 2026-07-23T11:53:10Z

JAVA-6222
This is the reference implementation for the Spec DRIVERS-3454 Support trace context propagation to the server specifications#1966
This PR also bump the wire protocol to 29 per https://jira.mongodb.org/browse/JAVA-6164

Spec proposal (OP_MSG section kind 3, W3C traceparent, hello tracingSupport negotiation) plus driver-sync POC design to validate it.

…r-sync)

…tion, wire-version gate)

…mpled with flags 00

…version gate supersedes)

Executed end-to-end against mongodb-mongo-master ee3a67f8 (9.0.0-alpha0): ServerSpanLinkageProseTest passes. Confirmed real server parameters (featureFlagOtelTraceSampling, openTelemetryTracingSampling BSON doc, opentelemetryTraceDirectory) and NDJSON export format. Fixed the prose test to assert operation-span parentage: the driver injects the traceparent from the OperationContext's operation span (per design 3.1), so the server span is a sibling of the client command span.

…crometer-tracing

…llMarked

…llMarked contract)

…bda)

…coded-bytes dependency)

…try section

…runbook

…e JAVA ticket)

…en, limitation noted)

Copilot

Pull request overview

Adds W3C traceparent propagation support to the server via a new OP_MSG telemetry section (wire version 29+), integrating with Micrometer tracing while keeping micrometer-tracing optional and guarded to avoid classpath linkage errors.

Changes:

Add OP_MSG kind-3 telemetry section encoding ({otel: {traceparent: ...}}) when a traced command span is available and the server wire version supports it.
Extend Micrometer tracing integration with TraceContext#traceParent() and a classpath guard to safely operate without micrometer-tracing present.
Add unit tests covering traceparent formatting/validation, classpath-absence safety, and command message telemetry section encoding/ordering.

Reviewed changes

Copilot reviewed 11 out of 11 changed files in this pull request and generated 2 comments.

Show a summary per file

File	Description
gradle/libs.versions.toml	Adds a Micrometer tracing library alias to support optional tracing integration.
driver-core/build.gradle.kts	Adds optional `micrometer-tracing` plus tracing test dependencies for new unit tests.
driver-core/src/test/unit/com/mongodb/internal/observability/micrometer/MicrometerTraceParentTest.java	Verifies traceparent formatting/validation and no-linkage-error behavior when tracing is absent.
driver-core/src/test/unit/com/mongodb/internal/connection/CommandMessageOtelTraceContextTest.java	Validates telemetry section encoding, ordering vs sequences, and command reconstruction behavior.
driver-core/src/main/com/mongodb/internal/operation/ServerVersionHelper.java	Introduces wire version constant for server 9.0 / wire version 29.
driver-core/src/main/com/mongodb/internal/observability/micrometer/TracingManager.java	Uses `CommandMessage` helpers instead of needing the encoded command document to populate tracing context.
driver-core/src/main/com/mongodb/internal/observability/micrometer/TraceContext.java	Adds `traceParent()` API for W3C context propagation.
driver-core/src/main/com/mongodb/internal/observability/micrometer/Span.java	Clarifies scope open/close semantics and no-op close behavior.
driver-core/src/main/com/mongodb/internal/observability/micrometer/MicrometerTracer.java	Implements `traceParent()` with optional-dependency guard and validation to avoid emitting rejected traceparents.
driver-core/src/main/com/mongodb/internal/connection/InternalStreamConnection.java	Ensures encoding can attach telemetry section by passing the tracing span into message encoding.
driver-core/src/main/com/mongodb/internal/connection/CommandMessage.java	Adds telemetry-section encoding + helpers (`getCommandName`, `getGetMoreCursorId`) and updates command reconstruction to ignore telemetry.

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

Copilot

Pull request overview

Copilot reviewed 11 out of 11 changed files in this pull request and generated 1 comment.

Comments suppressed due to low confidence (1)

driver-core/src/main/com/mongodb/internal/operation/ServerVersionHelper.java:38

LATEST_WIRE_VERSION is still set to the 8.0 value even though this PR introduces NINE_DOT_ZERO_WIRE_VERSION. This makes the constant name misleading and causes unit tests that use LATEST_WIRE_VERSION to stop representing the newest supported wire version.

    // Server 9.0 (WIRE_VERSION_90 = 29). Minimum wire version for the OP_MSG telemetry
    // section (OTel trace-context propagation, DRIVERS-3454).
    public static final int NINE_DOT_ZERO_WIRE_VERSION = 29;
    public static final int LATEST_WIRE_VERSION = EIGHT_DOT_ZERO_WIRE_VERSION;

Copilot

Pull request overview

Copilot reviewed 11 out of 11 changed files in this pull request and generated 1 comment.

Copilot

Pull request overview

Copilot reviewed 11 out of 11 changed files in this pull request and generated 1 comment.

Comments suppressed due to low confidence (1)

driver-core/src/main/com/mongodb/internal/operation/ServerVersionHelper.java:37

LATEST_WIRE_VERSION is now inconsistent with the newly introduced NINE_DOT_ZERO_WIRE_VERSION constant. Keeping it pinned to 8.0 makes test utilities and any future uses of LATEST_WIRE_VERSION silently exclude wire version 29 features (like OP_MSG telemetry).

    // Server 9.0 (WIRE_VERSION_90 = 29). Minimum wire version for the OP_MSG telemetry
    // section (OTel trace-context propagation, DRIVERS-3454).
    public static final int NINE_DOT_ZERO_WIRE_VERSION = 29;
    public static final int LATEST_WIRE_VERSION = EIGHT_DOT_ZERO_WIRE_VERSION;

Copilot

Pull request overview

Copilot reviewed 11 out of 11 changed files in this pull request and generated no new comments.

Comments suppressed due to low confidence (2)

driver-core/src/main/com/mongodb/internal/operation/ServerVersionHelper.java:38

LATEST_WIRE_VERSION is now inconsistent with the newly added NINE_DOT_ZERO_WIRE_VERSION constant (the file comments call 9.0 / wire version 29 the minimum for telemetry support, but LATEST_WIRE_VERSION still points at 8.0 / 25). This makes the meaning of “latest” ambiguous for test setups that import LATEST_WIRE_VERSION.

Consider either updating LATEST_WIRE_VERSION to NINE_DOT_ZERO_WIRE_VERSION, or adjusting naming/docs to clarify why 8.0 remains the “latest” for the driver/test suite.

    // Server 9.0 (WIRE_VERSION_90 = 29). Minimum wire version for the OP_MSG telemetry
    // section (OTel trace-context propagation, DRIVERS-3454).
    public static final int NINE_DOT_ZERO_WIRE_VERSION = 29;
    public static final int LATEST_WIRE_VERSION = EIGHT_DOT_ZERO_WIRE_VERSION;

driver-core/src/main/com/mongodb/internal/connection/CommandMessage.java:221

Javadoc has an unbalanced parenthesis: “(first key of the command document.” should be “(first key of the command document).”

     * The command name (first key of the command document. Available before {@code encode()} runs, unlike

Copilot

Pull request overview

Copilot reviewed 11 out of 11 changed files in this pull request and generated 1 comment.

Copilot

Pull request overview

Copilot reviewed 13 out of 13 changed files in this pull request and generated no new comments.

nhachicha added 30 commits June 1, 2026 18:51

DRIVERS-3454: design for OTel trace-context propagation over OP_MSG

f991058

Spec proposal (OP_MSG section kind 3, W3C traceparent, hello tracingSupport negotiation) plus driver-sync POC design to validate it.

DRIVERS-3454: implementation plan for OP_MSG trace-context POC (drive…

71944e9

…r-sync)

POC WIP

c23e2c9

DRIVERS-3454: design for reference implementation (BSON telemetry sec…

b7def2e

…tion, wire-version gate)

DRIVERS-3454: implementation plan for reference implementation

10a7e48

Merge remote-tracking branch 'origin/main' into nabil_otel_context

22460aa

DRIVERS-3454: add NINE_DOT_ZERO_WIRE_VERSION (29) constant

eb27cfa

DRIVERS-3454: guarantee traceParent() is server-valid; propagate unsa…

44fd4ca

…mpled with flags 00

DRIVERS-3454: write BSON telemetry section gated on maxWireVersion >= 29

9bd5c65

DRIVERS-3454: remove hello-capability plumbing and test toggle (wire-…

9931e89

…version gate supersedes)

DRIVERS-3454: prose-test definitions for trace-context propagation

d943d9e

DRIVERS-3454: e2e server-span linkage prose test (OTLP file exporter)

0176242

DRIVERS-3454: mark POC design superseded

321b7c3

DRIVERS-3454: guard traceparent production against absent optional mi…

c36118c

…crometer-tracing

DRIVERS-3454: drop dead null-check on Span.context() (non-null by @Nu…

9bf631a

…llMarked contract)

DRIVERS-3454: IDE polish (suppress always-inverted hint, EMPTY as lam…

f067ee1

…bda)

DRIVERS-3454: design for minimal spec change (OP_MSG + OTel specs)

9d7cfd6

DRIVERS-3454: plan for minimal spec change

4c3715f

DRIVERS-3454: design for command-span trace propagation (Option A)

fe04efd

DRIVERS-3454: plan for command-span trace propagation

346a959

DRIVERS-3454: createTracingSpan reads the raw command document (no en…

e295fa0

…coded-bytes dependency)

DRIVERS-3454: encode overload carries the command span for the teleme…

6db604c

…try section

DRIVERS-3454: create command span before encode; propagate its context

7352282

DRIVERS-3454: e2e + prose docs assert command-span parentage

b3e5358

DRIVERS-3454: note command-span amendment in reference-impl design

dc9fa67

DRIVERS-3454: fix stale mechanism comment in e2e test

80b0c2f

DRIVERS-3454: correct traceparent-mechanism wording in prose doc and …

4c5e5dc

…runbook

DRIVERS-3454: document pre-existing sync-path span-leak window (futur…

8cade28

…e JAVA ticket)

DRIVERS-3454: record prose-test decision (deferred; interop test chos…

7369f1f

…en, limitation noted)

update doc

4f417ff

nhachicha self-assigned this Jul 23, 2026

nhachicha mentioned this pull request Jul 23, 2026

JAVA-6222 OTEL context propagation #1996

Closed

nhachicha requested a review from Copilot July 23, 2026 11:54

Copilot started reviewing on behalf of nhachicha July 23, 2026 11:54 View session

nhachicha mentioned this pull request Jul 23, 2026

DRIVERS-3454 Support trace context propagation to the server mongodb/specifications#1966

Open

4 tasks

Copilot AI reviewed Jul 23, 2026

View reviewed changes

Comment thread driver-core/src/main/com/mongodb/internal/operation/ServerVersionHelper.java Outdated

Comment thread driver-core/src/main/com/mongodb/internal/connection/CommandMessage.java Outdated

nhachicha requested a review from Copilot July 23, 2026 12:00

Copilot started reviewing on behalf of nhachicha July 23, 2026 12:01 View session

Copilot AI reviewed Jul 23, 2026

View reviewed changes

Comment thread gradle/libs.versions.toml Outdated

nhachicha requested a review from Copilot July 23, 2026 12:09

Copilot started reviewing on behalf of nhachicha July 23, 2026 12:10 View session

Copilot AI reviewed Jul 23, 2026

View reviewed changes

Comment thread driver-core/src/main/com/mongodb/internal/connection/CommandMessage.java

nhachicha requested a review from Copilot July 23, 2026 12:16

Copilot started reviewing on behalf of nhachicha July 23, 2026 12:16 View session

Copilot AI reviewed Jul 23, 2026

View reviewed changes

Comment thread ...e/src/test/unit/com/mongodb/internal/observability/micrometer/MicrometerTraceParentTest.java

nhachicha requested a review from Copilot July 23, 2026 12:26

Copilot started reviewing on behalf of nhachicha July 23, 2026 12:26 View session

Copilot AI reviewed Jul 23, 2026

View reviewed changes

nhachicha requested a review from Copilot July 23, 2026 12:33

Copilot started reviewing on behalf of nhachicha July 23, 2026 12:34 View session

Copilot AI reviewed Jul 23, 2026

View reviewed changes

Comment thread driver-core/src/main/com/mongodb/internal/connection/CommandMessage.java

nhachicha added 2 commits July 23, 2026 15:26

Bump to wire protocol 29 and Copilot feedback

2ce9337

review feedback

73cf17b

nhachicha requested a review from Copilot July 23, 2026 14:44

Copilot started reviewing on behalf of nhachicha July 23, 2026 14:44 View session

Copilot AI reviewed Jul 23, 2026

View reviewed changes

nhachicha requested a review from rozza July 23, 2026 14:50

nhachicha marked this pull request as ready for review July 23, 2026 14:50

nhachicha requested a review from a team as a code owner July 23, 2026 14:50

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!

JAVA-6222 Support trace context propagation to the server#2022

JAVA-6222 Support trace context propagation to the server#2022
nhachicha wants to merge 49 commits into
mongodb:mainfrom
nhachicha:nabil_otel_context

nhachicha commented Jul 23, 2026 •

edited

Loading

Uh oh!

Copilot AI left a comment

Uh oh!

Uh oh!

Uh oh!

Copilot AI left a comment

Uh oh!

Uh oh!

Copilot AI left a comment

Uh oh!

Uh oh!

Copilot AI left a comment

Uh oh!

Uh oh!

Copilot AI left a comment

Uh oh!

Copilot AI left a comment

Uh oh!

Uh oh!

Copilot AI left a comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

Uh oh!

Conversation

nhachicha commented Jul 23, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Reviewed changes

Uh oh!

Uh oh!

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Uh oh!

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Uh oh!

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Uh oh!

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Uh oh!

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

nhachicha commented Jul 23, 2026 •

edited

Loading