Propagate W3C trace context for unsampled traces in event metadata

[w1am]

Fixes #400

Previously, the Java client only wrote tracing metadata ($traceId/$spanId) to appended events when the current trace was sampled. With head-based sampling in production, most events carried no trace context at all. Consumers reading them later couldn't link their spans back to the operation that produced the event, and events written this way can't be fixed retroactively.

Events now carry the standard W3C Trace Context in their metadata. The client writes $traceparent in the W3C format 00-{traceId}-{spanId}-{flags} whenever a trace is active, sampled or not, so consumers can always link back to the producer and see its real sampling decision. When the trace carries vendor state, such as a Datadog sampling decision, the client also writes $tracestate.

On read, the client prefers $traceparent and honors its actual flags. Events written by older clients only have $traceId/$spanId, and the client falls back to those, so existing data keeps working.

For a sampled trace, the client keeps writing the legacy fields so consumers on older client versions keep working:

{
  "$traceparent": "00-0af7651916cd43dd8448eb211c80319c-b7ad6b7169203331-01",
  "$tracestate": "dd=s:1",
  "$traceId": "0af7651916cd43dd8448eb211c80319c",
  "$spanId": "b7ad6b7169203331"
}

For an unsampled trace, which previously got nothing, the client writes only the new field:

{
  "$traceparent": "00-0af7651916cd43dd8448eb211c80319c-b7ad6b7169203331-00"
}

Upgrading

Consumers using the default ParentBased sampler now respect the producer's sampling decision, so events from unsampled traces no longer produce sampled consumer spans. This is the correct W3C behavior, but you might see fewer consumer spans if your producers sample aggressively.

If you registered an OpenTelemetry SDK with an alwaysOff sampler, event metadata is now stamped with $traceparent, where previously nothing was written.

The client now clears reserved metadata fields it manages: $tracestate on every append, and $traceId/$spanId when the trace is unsampled. If you were setting those fields yourself, they no longer survive the append.

Ref: DEV-1890

[linear-code]

DEV-1890

[qodo-code-review]

PR Summary by Qodo

Propagate W3C context for unsampled event traces

🐞 Bug fix 🧪 Tests 🕐 20-40 Minutes

AI Description

• Propagates W3C trace context for sampled and unsampled event-producing spans.
• Preserves sampling flags and vendor trace state when consumers extract parent context.
• Retains legacy sampled metadata and extraction fallback for backward compatibility.

Diagram

sequenceDiagram
    participant Producer as Producer Span
    participant Client as Java Client
    participant Propagator as W3C Propagator
    participant Metadata as Event Metadata
    participant Consumer as Consumer Span
    Producer->>Client: Append event
    Client->>Propagator: Inject active context
    Propagator->>Metadata: Write W3C fields
    Note over Client,Metadata: Sampled traces retain legacy IDs
    Consumer->>Client: Read event
    Client->>Propagator: Extract W3C context
    alt Valid traceparent
        Propagator-->>Client: Context flags and state
    else Missing or malformed
        Client->>Metadata: Read legacy IDs
    end
    Client-->>Consumer: Remote parent context

Loading

High-Level Assessment

Using OpenTelemetry's W3C propagator is the best approach because it preserves standard parsing, sampling flags, and trace state without maintaining custom serialization logic. Manual traceparent formatting was considered but would duplicate protocol validation and increase compatibility risk; retaining legacy fields only for sampled traces provides an appropriate migration path.

Files changed (7) +236 / -25

Enhancement (1) +2 / -0

ClientTelemetryConstants.javaDefine W3C tracing metadata keys +2/-0

Define W3C tracing metadata keys

• Adds public constants for the $traceParent and $traceState event metadata fields.

src/main/java/io/kurrent/dbclient/ClientTelemetryConstants.java

Bug fix (1) +85 / -23

ClientTelemetry.javaAdopt W3C event trace-context propagation +85/-23

Adopt W3C event trace-context propagation

• Injects traceparent for every valid span and tracestate when present, including unsampled traces. Extraction now prefers W3C metadata while falling back to sampled legacy identifiers, and stale legacy fields are removed from unsampled metadata.

src/main/java/io/kurrent/dbclient/ClientTelemetry.java

Tests (5) +149 / -2

TelemetryTests.javaRun propagation cases in the telemetry suite +1/-1

Run propagation cases in the telemetry suite

• Extends the existing telemetry test suite with the shared W3C tracing propagation contract.

src/test/java/io/kurrent/dbclient/TelemetryTests.java

TracingContextPropagationTests.javaCover W3C injection and extraction behavior +139/-0

Cover W3C injection and extraction behavior

• Adds reusable tests for sampled and unsampled injection, trace state, stale-field removal, invalid inputs, legacy fallback, extraction precedence, and round-trip preservation.

src/test/java/io/kurrent/dbclient/TracingContextPropagationTests.java

TracingContextPropagationUnitTests.javaProvide a unit-test propagation runner +4/-0

Provide a unit-test propagation runner

• Instantiates the shared tracing propagation test contract as a standalone JUnit test class.

src/test/java/io/kurrent/dbclient/TracingContextPropagationUnitTests.java

AppendTests.javaVerify untraced appends omit W3C metadata +3/-1

Verify untraced appends omit W3C metadata

• Extends append assertions to confirm traceparent and tracestate are absent when no active tracing context exists.

src/test/java/io/kurrent/dbclient/streams/AppendTests.java

StreamsTracingInstrumentationTests.javaAssert traceparent injection during appends +2/-0

Assert traceparent injection during appends

• Updates stream instrumentation coverage to require W3C traceparent metadata alongside legacy sampled trace identifiers.

src/test/java/io/kurrent/dbclient/telemetry/StreamsTracingInstrumentationTests.java

[qodo-code-review]

Code Review by Qodo

🐞 Bugs (0) 📘 Rule violations (0) 📎 Requirement gaps (0)

Great, no issues found!

Qodo reviewed your code and found no material issues that require review

Tip of the day

💡 Did you know, you can ask Qodo to dismiss a finding you disagree with, with your reason on record

More tips ↗ | Customize Qodo ↗ | Qodo docs ↗

[github-actions]

@w1am 👉 Created pull request targeting release/v1.2: #402