From 7bda01a9f292e086e7679a90c508b2594ac91b43 Mon Sep 17 00:00:00 2001 From: Diego Hurtado Date: Fri, 30 Oct 2026 13:28:01 -0600 Subject: [PATCH 01/12] Store the received B3 debug flag in the extracted context The B3 debug flag arrives either as the sampling state "d" in the single header or as x-b3-flags: 1 in the multi header form. Both were collapsed into the SAMPLED trace flag and the debug state itself was discarded, so nothing downstream could tell a debug trace from an ordinary sampled one. Keep the collapse into SAMPLED and additionally record the debug state under a context key, which the inject side can then read. The two forms are kept apart: a sampling state of "d" means debug only in the single header, since x-b3-sampled is not a carrier for it, even though this propagator has always accepted "d" there as a request to sample. --- .../opentelemetry/propagators/b3/__init__.py | 14 ++++- .../tests/test_b3_format.py | 52 ++++++++++++++++++- 2 files changed, 64 insertions(+), 2 deletions(-) diff --git a/propagator/opentelemetry-propagator-b3/src/opentelemetry/propagators/b3/__init__.py b/propagator/opentelemetry-propagator-b3/src/opentelemetry/propagators/b3/__init__.py index 0a6cff5d072..8e059f66124 100644 --- a/propagator/opentelemetry-propagator-b3/src/opentelemetry/propagators/b3/__init__.py +++ b/propagator/opentelemetry-propagator-b3/src/opentelemetry/propagators/b3/__init__.py @@ -7,7 +7,7 @@ from typing_extensions import deprecated from opentelemetry import trace -from opentelemetry.context import Context +from opentelemetry.context import Context, create_key, get_value, set_value from opentelemetry.propagators.textmap import ( CarrierT, Getter, @@ -18,6 +18,8 @@ ) from opentelemetry.trace import format_span_id, format_trace_id +_DEBUG_FLAG_KEY = create_key("b3-debug-flag") + class B3MultiFormat(TextMapPropagator): """Propagator for the B3 HTTP multi-header format. @@ -32,6 +34,8 @@ class B3MultiFormat(TextMapPropagator): SAMPLED_KEY = "x-b3-sampled" FLAGS_KEY = "x-b3-flags" _SAMPLE_PROPAGATE_VALUES = {"1", "True", "true", "d"} + _DEBUG_SAMPLED_VALUE = "d" + _DEBUG_FLAGS_VALUE = "1" _trace_id_regex = re_compile(r"[\da-fA-F]{16}|[\da-fA-F]{32}") _span_id_regex = re_compile(r"[\da-fA-F]{16}") @@ -47,6 +51,7 @@ def extract( span_id = trace.INVALID_SPAN_ID sampled = "0" flags = None + debug = False single_header = _extract_first_element(getter.get(carrier, self.SINGLE_HEADER_KEY)) if single_header: @@ -64,12 +69,16 @@ def extract( trace_id, span_id, sampled = fields elif len(fields) == 4: trace_id, span_id, sampled, _ = fields + + debug = sampled == self._DEBUG_SAMPLED_VALUE else: trace_id = _extract_first_element(getter.get(carrier, self.TRACE_ID_KEY)) or trace_id span_id = _extract_first_element(getter.get(carrier, self.SPAN_ID_KEY)) or span_id sampled = _extract_first_element(getter.get(carrier, self.SAMPLED_KEY)) or sampled flags = _extract_first_element(getter.get(carrier, self.FLAGS_KEY)) or flags + debug = flags == self._DEBUG_FLAGS_VALUE + if ( trace_id == trace.INVALID_TRACE_ID or span_id == trace.INVALID_SPAN_ID @@ -88,6 +97,9 @@ def extract( if sampled in self._SAMPLE_PROPAGATE_VALUES or flags == "1": options |= trace.TraceFlags.SAMPLED + if debug: + context = set_value(_DEBUG_FLAG_KEY, True, context) + return trace.set_span_in_context( trace.NonRecordingSpan( trace.SpanContext( diff --git a/propagator/opentelemetry-propagator-b3/tests/test_b3_format.py b/propagator/opentelemetry-propagator-b3/tests/test_b3_format.py index bad73518d44..9df95ccc7fd 100644 --- a/propagator/opentelemetry-propagator-b3/tests/test_b3_format.py +++ b/propagator/opentelemetry-propagator-b3/tests/test_b3_format.py @@ -6,8 +6,9 @@ from unittest.mock import Mock import opentelemetry.trace as trace_api -from opentelemetry.context import Context, get_current +from opentelemetry.context import Context, get_current, get_value from opentelemetry.propagators.b3 import ( # pylint: disable=no-name-in-module,import-error + _DEBUG_FLAG_KEY, B3MultiFormat, B3SingleFormat, ) @@ -202,6 +203,55 @@ def test_flags_and_sampling(self): self.assertSampled(new_carrier) + def test_extract_debug_flag_from_multi_header(self): + """A received x-b3-flags of "1" is stored in the extracted context.""" + propagator = self.get_propagator() + new_ctx = propagator.extract( + { + propagator.TRACE_ID_KEY: self.serialized_trace_id, + propagator.SPAN_ID_KEY: self.serialized_span_id, + propagator.FLAGS_KEY: "1", + } + ) + + self.assertTrue(get_value(_DEBUG_FLAG_KEY, new_ctx)) + + def test_extract_debug_flag_from_single_header(self): + """A received sampling state of "d" is stored in the extracted context.""" + propagator = self.get_propagator() + new_ctx = propagator.extract( + {propagator.SINGLE_HEADER_KEY: f"{self.serialized_trace_id}-{self.serialized_span_id}-d"} + ) + + self.assertTrue(get_value(_DEBUG_FLAG_KEY, new_ctx)) + + def test_extract_without_debug_flag(self): + """A sampled trace carrying no debug flag leaves none in the extracted context.""" + propagator = self.get_propagator() + new_ctx = propagator.extract( + { + propagator.TRACE_ID_KEY: self.serialized_trace_id, + propagator.SPAN_ID_KEY: self.serialized_span_id, + propagator.SAMPLED_KEY: "1", + } + ) + + self.assertIsNone(get_value(_DEBUG_FLAG_KEY, new_ctx)) + + def test_extract_multi_header_sampled_d_is_not_debug(self): + """In the multi header form only x-b3-flags carries the debug flag.""" + propagator = self.get_propagator() + new_ctx = propagator.extract( + { + propagator.TRACE_ID_KEY: self.serialized_trace_id, + propagator.SPAN_ID_KEY: self.serialized_span_id, + propagator.SAMPLED_KEY: "d", + } + ) + + self.assertIsNone(get_value(_DEBUG_FLAG_KEY, new_ctx)) + self.assertTrue(trace_api.get_current_span(new_ctx).get_span_context().trace_flags.sampled) + def test_derived_ctx_is_returned_for_success(self): """Ensure returned context is derived from the given context.""" old_ctx = Context({"k1": "v1"}) From c5b03438cb32a0f633fa4aa9c8f50c9275d31756 Mon Sep 17 00:00:00 2001 From: Diego Hurtado Date: Fri, 30 Oct 2026 13:32:54 -0600 Subject: [PATCH 02/12] Re-propagate the B3 debug flag on inject Inject only ever emitted a sampling decision of 1 or 0, so a debug trace arriving at a service left it as an ordinary sampled one and the debug state was lost for the rest of the trace. Read the debug state recorded by extract and re-emit it: the sampling state "d" in the single header form, and x-b3-flags: 1 in the multi header form. Debug implies an accept decision, so x-b3-sampled is set to 1 alongside it, which is what the Java implementation emits as well. x-b3-flags joins the fields of B3MultiFormat, since inject can now set it and a reused carrier has to have it cleared. --- .../opentelemetry/propagators/b3/__init__.py | 13 ++- .../tests/test_b3_format.py | 90 +++++++++++++++++-- 2 files changed, 96 insertions(+), 7 deletions(-) diff --git a/propagator/opentelemetry-propagator-b3/src/opentelemetry/propagators/b3/__init__.py b/propagator/opentelemetry-propagator-b3/src/opentelemetry/propagators/b3/__init__.py index 8e059f66124..2db5451e443 100644 --- a/propagator/opentelemetry-propagator-b3/src/opentelemetry/propagators/b3/__init__.py +++ b/propagator/opentelemetry-propagator-b3/src/opentelemetry/propagators/b3/__init__.py @@ -127,13 +127,16 @@ def inject( return sampled = (trace.TraceFlags.SAMPLED & span_context.trace_flags) != 0 + debug = get_value(_DEBUG_FLAG_KEY, context) is True setter.set( carrier, self.TRACE_ID_KEY, format_trace_id(span_context.trace_id), ) setter.set(carrier, self.SPAN_ID_KEY, format_span_id(span_context.span_id)) - setter.set(carrier, self.SAMPLED_KEY, "1" if sampled else "0") + if debug: + setter.set(carrier, self.FLAGS_KEY, self._DEBUG_FLAGS_VALUE) + setter.set(carrier, self.SAMPLED_KEY, "1" if sampled or debug else "0") @property def fields(self) -> set[str]: @@ -141,6 +144,7 @@ def fields(self) -> set[str]: self.TRACE_ID_KEY, self.SPAN_ID_KEY, self.SAMPLED_KEY, + self.FLAGS_KEY, } @@ -165,10 +169,15 @@ def inject( sampled = (trace.TraceFlags.SAMPLED & span_context.trace_flags) != 0 + if get_value(_DEBUG_FLAG_KEY, context) is True: + sampling_state = self._DEBUG_SAMPLED_VALUE + else: + sampling_state = "1" if sampled else "0" + fields = [ format_trace_id(span_context.trace_id), format_span_id(span_context.span_id), - "1" if sampled else "0", + sampling_state, ] setter.set(carrier, self.SINGLE_HEADER_KEY, "-".join(fields)) diff --git a/propagator/opentelemetry-propagator-b3/tests/test_b3_format.py b/propagator/opentelemetry-propagator-b3/tests/test_b3_format.py index 9df95ccc7fd..b223eaf6a02 100644 --- a/propagator/opentelemetry-propagator-b3/tests/test_b3_format.py +++ b/propagator/opentelemetry-propagator-b3/tests/test_b3_format.py @@ -36,7 +36,7 @@ def get_child_parent_new_carrier(old_carrier, propagator): ) new_carrier = {} - ctx = trace_api.set_span_in_context(child) + ctx = trace_api.set_span_in_context(child, ctx) propagator.inject(new_carrier, context=ctx) return child, parent, new_carrier @@ -77,6 +77,12 @@ def assertSampled(self, carrier): def assertNotSampled(self, carrier): pass + def assertDebug(self, carrier): + pass + + def assertNotDebug(self, carrier): + pass + def test_extract_multi_header(self): """Test the extraction of B3 headers.""" propagator = self.get_propagator() @@ -178,7 +184,7 @@ def test_disabled_sampling(self): self.assertNotSampled(new_carrier) def test_flags(self): - """x-b3-flags set to "1" should result in propagation.""" + """x-b3-flags set to "1" should result in propagation of the debug flag.""" propagator = self.get_propagator() _, _, new_carrier = self.get_child_parent_new_carrier( { @@ -188,10 +194,10 @@ def test_flags(self): } ) - self.assertSampled(new_carrier) + self.assertDebug(new_carrier) def test_flags_and_sampling(self): - """Propagate if b3 flags and sampling are set.""" + """Propagate the debug flag if b3 flags and sampling are set.""" propagator = self.get_propagator() _, _, new_carrier = self.get_child_parent_new_carrier( { @@ -201,7 +207,7 @@ def test_flags_and_sampling(self): } ) - self.assertSampled(new_carrier) + self.assertDebug(new_carrier) def test_extract_debug_flag_from_multi_header(self): """A received x-b3-flags of "1" is stored in the extracted context.""" @@ -252,6 +258,54 @@ def test_extract_multi_header_sampled_d_is_not_debug(self): self.assertIsNone(get_value(_DEBUG_FLAG_KEY, new_ctx)) self.assertTrue(trace_api.get_current_span(new_ctx).get_span_context().trace_flags.sampled) + def test_inject_debug_flag_received_in_single_header(self): + """A debug flag received as the sampling state "d" is re-propagated on inject.""" + propagator = self.get_propagator() + _, _, new_carrier = self.get_child_parent_new_carrier( + {propagator.SINGLE_HEADER_KEY: f"{self.serialized_trace_id}-{self.serialized_span_id}-d"} + ) + + self.assertDebug(new_carrier) + + def test_inject_without_debug_flag(self): + """A sampled trace with no received debug flag is injected without one.""" + propagator = self.get_propagator() + _, _, new_carrier = self.get_child_parent_new_carrier( + { + propagator.TRACE_ID_KEY: self.serialized_trace_id, + propagator.SPAN_ID_KEY: self.serialized_span_id, + propagator.SAMPLED_KEY: "1", + } + ) + + self.assertNotDebug(new_carrier) + self.assertSampled(new_carrier) + + def test_inject_debug_flag_for_unsampled_span(self): + """A received debug flag forces the injected sampling decision to accept.""" + propagator = self.get_propagator() + ctx = propagator.extract( + { + propagator.TRACE_ID_KEY: self.serialized_trace_id, + propagator.SPAN_ID_KEY: self.serialized_span_id, + propagator.FLAGS_KEY: "1", + } + ) + child = trace._Span( + "child", + trace_api.SpanContext( + int(self.serialized_trace_id, 16), + id_generator.RandomIdGenerator().generate_span_id(), + is_remote=False, + trace_flags=trace_api.TraceFlags(trace_api.TraceFlags.DEFAULT), + ), + ) + + new_carrier = {} + propagator.inject(new_carrier, context=trace_api.set_span_in_context(child, ctx)) + + self.assertDebug(new_carrier) + def test_derived_ctx_is_returned_for_success(self): """Ensure returned context is derived from the given context.""" old_ctx = Context({"k1": "v1"}) @@ -450,6 +504,18 @@ def test_fields(self): with tracer.start_as_current_span("child"): propagator.inject({}, setter=mock_setter) + propagator.inject( + {}, + context=propagator.extract( + { + propagator.TRACE_ID_KEY: self.serialized_trace_id, + propagator.SPAN_ID_KEY: self.serialized_span_id, + propagator.FLAGS_KEY: "1", + } + ), + setter=mock_setter, + ) + inject_fields = set() for call in mock_setter.mock_calls: @@ -498,6 +564,14 @@ def assertSampled(self, carrier): def assertNotSampled(self, carrier): self.assertEqual(carrier[self.get_propagator().SAMPLED_KEY], "0") + def assertDebug(self, carrier): + propagator = self.get_propagator() + self.assertEqual(carrier[propagator.FLAGS_KEY], "1") + self.assertEqual(carrier[propagator.SAMPLED_KEY], "1") + + def assertNotDebug(self, carrier): + self.assertNotIn(self.get_propagator().FLAGS_KEY, carrier) + class TestB3SingleFormat(AbstractB3FormatTestCase, unittest.TestCase): @classmethod @@ -513,3 +587,9 @@ def assertSampled(self, carrier): def assertNotSampled(self, carrier): self.assertEqual(carrier[self.get_propagator().SINGLE_HEADER_KEY].split("-")[2], "0") + + def assertDebug(self, carrier): + self.assertEqual(carrier[self.get_propagator().SINGLE_HEADER_KEY].split("-")[2], "d") + + def assertNotDebug(self, carrier): + self.assertNotEqual(carrier[self.get_propagator().SINGLE_HEADER_KEY].split("-")[2], "d") From 6d221ba40ab6ea4803d589bcd85ff0e4fca5e532 Mon Sep 17 00:00:00 2001 From: Diego Hurtado Date: Fri, 30 Oct 2026 13:34:25 -0600 Subject: [PATCH 03/12] Add changelog entry for the B3 debug flag fix --- .changelog/52.fixed | 1 + 1 file changed, 1 insertion(+) create mode 100644 .changelog/52.fixed diff --git a/.changelog/52.fixed b/.changelog/52.fixed new file mode 100644 index 00000000000..9cdf454ca44 --- /dev/null +++ b/.changelog/52.fixed @@ -0,0 +1 @@ +`opentelemetry-propagator-b3`: preserve and re-propagate a received debug flag From cb95d81afa974e4c730fd002bd9a5fb213d24ed3 Mon Sep 17 00:00:00 2001 From: Diego Hurtado Date: Fri, 30 Oct 2026 13:47:00 -0600 Subject: [PATCH 04/12] Make the extracted debug flag depend on the carrier alone extract takes an optional context to extend, and it only ever set the debug flag, never cleared it. Extracting a carrier that carries no debug flag into a context that already held one therefore returned a context still marked for debug, and injecting it put the debug flag on the wire for a trace that was never marked for it. Record the debug state of the carrier being extracted, whether or not it is set, so the state the inject side reads is the state the carrier actually carried. --- .../opentelemetry/propagators/b3/__init__.py | 3 +- .../tests/test_b3_format.py | 30 +++++++++++++++++-- 2 files changed, 29 insertions(+), 4 deletions(-) diff --git a/propagator/opentelemetry-propagator-b3/src/opentelemetry/propagators/b3/__init__.py b/propagator/opentelemetry-propagator-b3/src/opentelemetry/propagators/b3/__init__.py index 2db5451e443..4d273d6c346 100644 --- a/propagator/opentelemetry-propagator-b3/src/opentelemetry/propagators/b3/__init__.py +++ b/propagator/opentelemetry-propagator-b3/src/opentelemetry/propagators/b3/__init__.py @@ -97,8 +97,7 @@ def extract( if sampled in self._SAMPLE_PROPAGATE_VALUES or flags == "1": options |= trace.TraceFlags.SAMPLED - if debug: - context = set_value(_DEBUG_FLAG_KEY, True, context) + context = set_value(_DEBUG_FLAG_KEY, debug, context) return trace.set_span_in_context( trace.NonRecordingSpan( diff --git a/propagator/opentelemetry-propagator-b3/tests/test_b3_format.py b/propagator/opentelemetry-propagator-b3/tests/test_b3_format.py index b223eaf6a02..948a7d8fd88 100644 --- a/propagator/opentelemetry-propagator-b3/tests/test_b3_format.py +++ b/propagator/opentelemetry-propagator-b3/tests/test_b3_format.py @@ -242,7 +242,7 @@ def test_extract_without_debug_flag(self): } ) - self.assertIsNone(get_value(_DEBUG_FLAG_KEY, new_ctx)) + self.assertFalse(get_value(_DEBUG_FLAG_KEY, new_ctx)) def test_extract_multi_header_sampled_d_is_not_debug(self): """In the multi header form only x-b3-flags carries the debug flag.""" @@ -255,7 +255,7 @@ def test_extract_multi_header_sampled_d_is_not_debug(self): } ) - self.assertIsNone(get_value(_DEBUG_FLAG_KEY, new_ctx)) + self.assertFalse(get_value(_DEBUG_FLAG_KEY, new_ctx)) self.assertTrue(trace_api.get_current_span(new_ctx).get_span_context().trace_flags.sampled) def test_inject_debug_flag_received_in_single_header(self): @@ -306,6 +306,32 @@ def test_inject_debug_flag_for_unsampled_span(self): self.assertDebug(new_carrier) + def test_extract_clears_a_debug_flag_left_by_an_earlier_carrier(self): + """The debug flag in the returned context comes from the carrier being extracted.""" + propagator = self.get_propagator() + debug_ctx = propagator.extract( + { + propagator.TRACE_ID_KEY: self.serialized_trace_id, + propagator.SPAN_ID_KEY: self.serialized_span_id, + propagator.FLAGS_KEY: "1", + } + ) + new_ctx = propagator.extract( + { + propagator.TRACE_ID_KEY: self.serialized_trace_id, + propagator.SPAN_ID_KEY: self.serialized_span_id, + propagator.SAMPLED_KEY: "1", + }, + debug_ctx, + ) + + self.assertFalse(get_value(_DEBUG_FLAG_KEY, new_ctx)) + + new_carrier = {} + propagator.inject(new_carrier, context=new_ctx) + + self.assertNotDebug(new_carrier) + def test_derived_ctx_is_returned_for_success(self): """Ensure returned context is derived from the given context.""" old_ctx = Context({"k1": "v1"}) From d2ff3dd65dda0a0e6a34d3ce37283653d26dbd88 Mon Sep 17 00:00:00 2001 From: Diego Hurtado Date: Fri, 30 Oct 2026 13:47:15 -0600 Subject: [PATCH 05/12] Cover the attached context and the flags against sampled case Two paths the suite did not reach. Instrumentation activates an extracted context by attaching it and then calls inject with no context argument, and every test so far passed the context to inject explicitly. test_flags_and_sampling named a combination of x-b3-flags and x-b3-sampled that it never built, leaving it byte for byte the same carrier as test_flags, so the case where the two headers disagree had no test at all. --- .../tests/test_b3_format.py | 25 +++++++++++++++++-- 1 file changed, 23 insertions(+), 2 deletions(-) diff --git a/propagator/opentelemetry-propagator-b3/tests/test_b3_format.py b/propagator/opentelemetry-propagator-b3/tests/test_b3_format.py index 948a7d8fd88..ec53861ace8 100644 --- a/propagator/opentelemetry-propagator-b3/tests/test_b3_format.py +++ b/propagator/opentelemetry-propagator-b3/tests/test_b3_format.py @@ -6,7 +6,7 @@ from unittest.mock import Mock import opentelemetry.trace as trace_api -from opentelemetry.context import Context, get_current, get_value +from opentelemetry.context import Context, attach, detach, get_current, get_value from opentelemetry.propagators.b3 import ( # pylint: disable=no-name-in-module,import-error _DEBUG_FLAG_KEY, B3MultiFormat, @@ -197,13 +197,14 @@ def test_flags(self): self.assertDebug(new_carrier) def test_flags_and_sampling(self): - """Propagate the debug flag if b3 flags and sampling are set.""" + """x-b3-flags set to "1" wins over x-b3-sampled set to "0".""" propagator = self.get_propagator() _, _, new_carrier = self.get_child_parent_new_carrier( { propagator.TRACE_ID_KEY: self.serialized_trace_id, propagator.SPAN_ID_KEY: self.serialized_span_id, propagator.FLAGS_KEY: "1", + propagator.SAMPLED_KEY: "0", } ) @@ -332,6 +333,26 @@ def test_extract_clears_a_debug_flag_left_by_an_earlier_carrier(self): self.assertNotDebug(new_carrier) + def test_inject_debug_flag_from_attached_context(self): + """The debug flag survives the extracted context being attached rather than passed.""" + propagator = self.get_propagator() + token = attach( + propagator.extract( + { + propagator.TRACE_ID_KEY: self.serialized_trace_id, + propagator.SPAN_ID_KEY: self.serialized_span_id, + propagator.FLAGS_KEY: "1", + } + ) + ) + try: + new_carrier = {} + propagator.inject(new_carrier) + finally: + detach(token) + + self.assertDebug(new_carrier) + def test_derived_ctx_is_returned_for_success(self): """Ensure returned context is derived from the given context.""" old_ctx = Context({"k1": "v1"}) From ceaefa6186543c21791995376f5b08a50ca6e591 Mon Sep 17 00:00:00 2001 From: Diego Hurtado Date: Fri, 30 Oct 2026 13:58:26 -0600 Subject: [PATCH 06/12] Keep asserting that x-b3-flags turns on the sampled trace flag test_flags and test_flags_and_sampling used to prove that x-b3-flags: 1 sets TraceFlags.SAMPLED on the extracted span context. Rewriting them to assert the debug flag replaced that with an assertion the inject side satisfies from the debug state alone, so deleting the flags clause from extract left the whole suite green. Assert the trace flag on the extracted parent as well as the debug flag on the injected carrier. --- .../opentelemetry-propagator-b3/tests/test_b3_format.py | 6 ++++-- 1 file changed, 4 insertions(+), 2 deletions(-) diff --git a/propagator/opentelemetry-propagator-b3/tests/test_b3_format.py b/propagator/opentelemetry-propagator-b3/tests/test_b3_format.py index ec53861ace8..9207b144fce 100644 --- a/propagator/opentelemetry-propagator-b3/tests/test_b3_format.py +++ b/propagator/opentelemetry-propagator-b3/tests/test_b3_format.py @@ -186,7 +186,7 @@ def test_disabled_sampling(self): def test_flags(self): """x-b3-flags set to "1" should result in propagation of the debug flag.""" propagator = self.get_propagator() - _, _, new_carrier = self.get_child_parent_new_carrier( + _, parent, new_carrier = self.get_child_parent_new_carrier( { propagator.TRACE_ID_KEY: self.serialized_trace_id, propagator.SPAN_ID_KEY: self.serialized_span_id, @@ -194,12 +194,13 @@ def test_flags(self): } ) + self.assertTrue(parent.context.trace_flags.sampled) self.assertDebug(new_carrier) def test_flags_and_sampling(self): """x-b3-flags set to "1" wins over x-b3-sampled set to "0".""" propagator = self.get_propagator() - _, _, new_carrier = self.get_child_parent_new_carrier( + _, parent, new_carrier = self.get_child_parent_new_carrier( { propagator.TRACE_ID_KEY: self.serialized_trace_id, propagator.SPAN_ID_KEY: self.serialized_span_id, @@ -208,6 +209,7 @@ def test_flags_and_sampling(self): } ) + self.assertTrue(parent.context.trace_flags.sampled) self.assertDebug(new_carrier) def test_extract_debug_flag_from_multi_header(self): From ab11a1baecde76ed6cf15998ef48c7e3adecac58 Mon Sep 17 00:00:00 2001 From: Diego Hurtado Date: Fri, 30 Oct 2026 14:11:08 -0600 Subject: [PATCH 07/12] Keep a debug flag that arrives with no trace or span ids The B3 specification allows a sampling state to be sent on its own, so "b3: d" and "x-b3-flags: 1" are both complete carriers that mark a trace for debug without naming one. extract returned early on the missing ids and threw the flag away, and the service then started a root trace and injected an ordinary sampled decision. Store the flag on that path, and only when no ids were supplied at all, so a carrier whose ids are present but unparsable still leaves the context alone. --- .../src/opentelemetry/propagators/b3/__init__.py | 2 ++ .../tests/test_b3_format.py | 14 ++++++++++++++ 2 files changed, 16 insertions(+) diff --git a/propagator/opentelemetry-propagator-b3/src/opentelemetry/propagators/b3/__init__.py b/propagator/opentelemetry-propagator-b3/src/opentelemetry/propagators/b3/__init__.py index 4d273d6c346..5e9bb853f78 100644 --- a/propagator/opentelemetry-propagator-b3/src/opentelemetry/propagators/b3/__init__.py +++ b/propagator/opentelemetry-propagator-b3/src/opentelemetry/propagators/b3/__init__.py @@ -85,6 +85,8 @@ def extract( or self._trace_id_regex.fullmatch(trace_id) is None or self._span_id_regex.fullmatch(span_id) is None ): + if debug and trace_id == trace.INVALID_TRACE_ID and span_id == trace.INVALID_SPAN_ID: + context = set_value(_DEBUG_FLAG_KEY, True, context) return context trace_id = int(trace_id, 16) diff --git a/propagator/opentelemetry-propagator-b3/tests/test_b3_format.py b/propagator/opentelemetry-propagator-b3/tests/test_b3_format.py index 9207b144fce..d4247186aa1 100644 --- a/propagator/opentelemetry-propagator-b3/tests/test_b3_format.py +++ b/propagator/opentelemetry-propagator-b3/tests/test_b3_format.py @@ -309,6 +309,20 @@ def test_inject_debug_flag_for_unsampled_span(self): self.assertDebug(new_carrier) + def test_extract_debug_flag_from_single_header_without_ids(self): + """A sampling state of "d" sent on its own still carries the debug flag.""" + propagator = self.get_propagator() + new_ctx = propagator.extract({propagator.SINGLE_HEADER_KEY: "d"}) + + self.assertTrue(get_value(_DEBUG_FLAG_KEY, new_ctx)) + + def test_extract_debug_flag_from_multi_header_without_ids(self): + """An x-b3-flags of "1" sent on its own still carries the debug flag.""" + propagator = self.get_propagator() + new_ctx = propagator.extract({propagator.FLAGS_KEY: "1"}) + + self.assertTrue(get_value(_DEBUG_FLAG_KEY, new_ctx)) + def test_extract_clears_a_debug_flag_left_by_an_earlier_carrier(self): """The debug flag in the returned context comes from the carrier being extracted.""" propagator = self.get_propagator() From 13b67ddf5a1e3646ee4e5003c853599c75ef3639 Mon Sep 17 00:00:00 2001 From: Diego Hurtado Date: Fri, 30 Oct 2026 14:21:08 -0600 Subject: [PATCH 08/12] Pin the header written for a debug flag received with no ids Every test that reached inject used a carrier with ids, so the store on the early-return path was only ever asserted through the context and never through what goes on the wire. --- .../tests/test_b3_format.py | 14 ++++++++++++++ 1 file changed, 14 insertions(+) diff --git a/propagator/opentelemetry-propagator-b3/tests/test_b3_format.py b/propagator/opentelemetry-propagator-b3/tests/test_b3_format.py index d4247186aa1..b435fe2ed66 100644 --- a/propagator/opentelemetry-propagator-b3/tests/test_b3_format.py +++ b/propagator/opentelemetry-propagator-b3/tests/test_b3_format.py @@ -349,6 +349,20 @@ def test_extract_clears_a_debug_flag_left_by_an_earlier_carrier(self): self.assertNotDebug(new_carrier) + def test_inject_debug_flag_received_without_ids(self): + """A debug flag received with no ids is re-propagated onto the span that follows it.""" + propagator = self.get_propagator() + tracer = trace.TracerProvider().get_tracer("sdk_tracer_provider") + token = attach(propagator.extract({propagator.SINGLE_HEADER_KEY: "d"})) + try: + new_carrier = {} + with tracer.start_as_current_span("server"): + propagator.inject(new_carrier) + finally: + detach(token) + + self.assertDebug(new_carrier) + def test_inject_debug_flag_from_attached_context(self): """The debug flag survives the extracted context being attached rather than passed.""" propagator = self.get_propagator() From 69ed1a88aef51e86ad77515dc937723726f9f0e5 Mon Sep 17 00:00:00 2001 From: Diego Hurtado Date: Fri, 30 Oct 2026 17:47:49 -0600 Subject: [PATCH 09/12] Rename the changelog fragment to the pull request number --- .changelog/{52.fixed => 78.fixed} | 0 1 file changed, 0 insertions(+), 0 deletions(-) rename .changelog/{52.fixed => 78.fixed} (100%) diff --git a/.changelog/52.fixed b/.changelog/78.fixed similarity index 100% rename from .changelog/52.fixed rename to .changelog/78.fixed From 9c823b95aaf9a9dd597fa41e379be7ec8a302f65 Mon Sep 17 00:00:00 2001 From: Diego Hurtado Date: Fri, 30 Oct 2026 18:01:11 -0600 Subject: [PATCH 10/12] Pin that the debug check compares against an exact value Nothing failed when either comparison was relaxed to a presence check, so an x-b3-flags of "0" read as debug and a single header accept state of "1" read as debug, and the suite stayed green both times. --- .../tests/test_b3_format.py | 22 +++++++++++++++++++ 1 file changed, 22 insertions(+) diff --git a/propagator/opentelemetry-propagator-b3/tests/test_b3_format.py b/propagator/opentelemetry-propagator-b3/tests/test_b3_format.py index b435fe2ed66..1a78a4908c6 100644 --- a/propagator/opentelemetry-propagator-b3/tests/test_b3_format.py +++ b/propagator/opentelemetry-propagator-b3/tests/test_b3_format.py @@ -247,6 +247,28 @@ def test_extract_without_debug_flag(self): self.assertFalse(get_value(_DEBUG_FLAG_KEY, new_ctx)) + def test_extract_without_debug_flag_for_an_explicit_zero(self): + """An x-b3-flags of "0" is not a debug flag.""" + propagator = self.get_propagator() + new_ctx = propagator.extract( + { + propagator.TRACE_ID_KEY: self.serialized_trace_id, + propagator.SPAN_ID_KEY: self.serialized_span_id, + propagator.FLAGS_KEY: "0", + } + ) + + self.assertFalse(get_value(_DEBUG_FLAG_KEY, new_ctx)) + + def test_extract_without_debug_flag_for_a_single_header_accept(self): + """A single header sampling state of "1" is not a debug flag.""" + propagator = self.get_propagator() + new_ctx = propagator.extract( + {propagator.SINGLE_HEADER_KEY: f"{self.serialized_trace_id}-{self.serialized_span_id}-1"} + ) + + self.assertFalse(get_value(_DEBUG_FLAG_KEY, new_ctx)) + def test_extract_multi_header_sampled_d_is_not_debug(self): """In the multi header form only x-b3-flags carries the debug flag.""" propagator = self.get_propagator() From 4866385f7bd906f966f1906a354bd419516cd3fa Mon Sep 17 00:00:00 2001 From: Diego Hurtado Date: Fri, 30 Oct 2026 18:11:29 -0600 Subject: [PATCH 11/12] Drop the unread debug initialiser in extract --- .../src/opentelemetry/propagators/b3/__init__.py | 1 - 1 file changed, 1 deletion(-) diff --git a/propagator/opentelemetry-propagator-b3/src/opentelemetry/propagators/b3/__init__.py b/propagator/opentelemetry-propagator-b3/src/opentelemetry/propagators/b3/__init__.py index 5e9bb853f78..446bef94d02 100644 --- a/propagator/opentelemetry-propagator-b3/src/opentelemetry/propagators/b3/__init__.py +++ b/propagator/opentelemetry-propagator-b3/src/opentelemetry/propagators/b3/__init__.py @@ -51,7 +51,6 @@ def extract( span_id = trace.INVALID_SPAN_ID sampled = "0" flags = None - debug = False single_header = _extract_first_element(getter.get(carrier, self.SINGLE_HEADER_KEY)) if single_header: From 681f73ed295e353905cfb82f31b462c3cbb02e3f Mon Sep 17 00:00:00 2001 From: Diego Hurtado Date: Sat, 31 Oct 2026 08:35:42 -0600 Subject: [PATCH 12/12] Name the changelog fragment after the pull request --- .changelog/{78.fixed => 5870.fixed} | 0 1 file changed, 0 insertions(+), 0 deletions(-) rename .changelog/{78.fixed => 5870.fixed} (100%) diff --git a/.changelog/78.fixed b/.changelog/5870.fixed similarity index 100% rename from .changelog/78.fixed rename to .changelog/5870.fixed