oss_15_b3_debug_flag_propagation

[ocelotl]

Closes #19

Preserve and re-propagate the B3 debug flag (Linear OSS-15, finding P1). Extract stores the received debug state in a dedicated context key; inject re-emits it — x-b3-flags: 1 (multi-header) / d in the sampling position (single-header). Normal sampled/unsampled behavior unchanged.

Validation: scope contained to propagator-b3 + changelog; propagator-b3 suite 56 passed.

Linear issue: https://linear.app/dash0/issue/OSS-15/p1-b3-propagator-debug-flag-not-preservedre-propagated-on-inject-must

[ocelotl]

🔒 Internal (dash0) — not for upstream.

• Linear: https://linear.app/dash0/issue/OSS-15/p1-b3-propagator-debug-flag-not-preservedre-propagated-on-inject-must (finding P1)
• Closes: oss_15_b3_debug_flag_propagation #19 · Branch/worktree: oss_15_b3_debug_flag_propagation · Commit: 500252382
• Validation: propagator-b3 suite 56 passed (re-run by supervisor); scope contained to propagator-b3 + changelog.

[ocelotl]

📣 Public-facing draft — to be used for the upstream PR in open-telemetry/opentelemetry-python. No internal references; copy verbatim.

Title: Preserve and re-propagate the B3 debug flag

What

The B3 propagators now preserve a received debug flag and re-propagate it downstream:

• Extract stores the received debug state in a dedicated context key (created with opentelemetry.context.create_key).
• B3MultiFormat.inject emits x-b3-flags: 1 (and omits x-b3-sampled, since debug implies sampling) when the debug flag was received.
• B3SingleFormat.inject emits d in the sampling position of the single header when the debug flag was received.
• Non-debug sampled/unsampled behavior is unchanged.

Why

Previously the debug indicator (d / x-b3-flags: 1) was collapsed into the SAMPLED trace flag on extract and never stored, and inject only ever emitted 1/0. A debug flag sent by an upstream service was therefore silently dropped.

Spec

specification/context/api-propagators.md (B3 requirements) states that a received debug flag MUST be preserved and re-propagated. This matches the OpenTelemetry Java implementation, which keeps the debug flag in a context entry and re-emits it on inject.

Tests

• New test_debug_flag_roundtrip: extract→inject preserves the debug flag in both single-header (…-d) and multi-header (x-b3-flags: 1) formats.
• New test_non_debug_context_does_not_emit_debug: a normal sampled context injects sampled and never emits the debug flag.
• test_fields extended to exercise the debug inject path so the injected-field set still matches the fields property.
• Full propagator-b3 suite: 56 passed.