oss_15_b3_debug_flag_propagation

[ocelotl]

B3 propagator: preserve and re-propagate a received debug flag on inject (Linear OSS-15, finding P1).

Branch / worktree: oss_15_b3_debug_flag_propagation

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.

Tracking for the B3 debug-flag fix.

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

[ocelotl]

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

Title: B3 propagators drop the received debug flag instead of re-propagating it

Description

The B3 propagators in opentelemetry-propagator-b3 do not preserve a received B3 debug flag. On extract, the debug indicator (d in the single header, x-b3-flags: 1 in the multi header) is collapsed into the SAMPLED trace flag and the fact that it was a debug flag is lost. On inject, the propagator only ever emits 1/0, so a downstream service never sees the debug flag that an upstream service sent.

Evidence

propagator/opentelemetry-propagator-b3/src/opentelemetry/propagators/b3/__init__.py:

• Extract (~L97-103): if sampled in self._SAMPLE_PROPAGATE_VALUES or flags == "1": options |= trace.TraceFlags.SAMPLED — the d/flags input only sets SAMPLED; the debug state is never stored.
• Multi-header inject (~L140): setter.set(carrier, self.SAMPLED_KEY, "1" if sampled else "0") — never emits x-b3-flags.
• Single-header inject (~L172-176): the sampling field is only ever "1"/"0", never "d".

Spec

specification/context/api-propagators.md (B3 requirements): B3 implementations MUST support the debug (d) flag, and a received debug flag MUST be preserved and re-propagated to downstream services.

Reference implementation

OpenTelemetry Java stores the received B3 debug flag in a context entry on extract and re-emits it on inject (X-B3-Flags: 1 for multi-header, d in the sampling position for single-header).

Proposed fix

On extract, store the received debug state in a dedicated context key. On inject, re-emit it — X-B3-Flags: 1 for the multi-header format and d in the single-header sampling position — whenever the debug flag was received. Normal sampled/unsampled behavior is unchanged.