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.

[github-actions]

This PR has been automatically marked as stale because it has not had any activity for 14 days. It will be closed if no further activity occurs within 14 days of this comment.
If you're still working on this, please add a comment or push new commits.