Rename HTTPTextFormat to TextMapPropagator (#1085)

Author: alrex

docs/conf.py

@@ -103,17 +103,14 @@
     # with "class reference target not found: ObjectProxy".
     ("py:class", "ObjectProxy"),
     # TODO: Understand why sphinx is not able to find this local class
-    (
-        "py:class",
-        "opentelemetry.trace.propagation.httptextformat.HTTPTextFormat",
-    ),
+    ("py:class", "opentelemetry.trace.propagation.textmap.TextMapPropagator",),
     (
         "any",
-        "opentelemetry.trace.propagation.httptextformat.HTTPTextFormat.extract",
+        "opentelemetry.trace.propagation.textmap.TextMapPropagator.extract",
     ),
     (
         "any",
-        "opentelemetry.trace.propagation.httptextformat.HTTPTextFormat.inject",
+        "opentelemetry.trace.propagation.textmap.TextMapPropagator.inject",
     ),
 ]
 

docs/examples/datadog_exporter/server.py

@@ -35,19 +35,19 @@
 )
 
 # append Datadog format for propagation to and from Datadog instrumented services
-global_httptextformat = propagators.get_global_httptextformat()
+global_textmap = propagators.get_global_textmap()
 if isinstance(
-    global_httptextformat, propagators.composite.CompositeHTTPPropagator
+    global_textmap, propagators.composite.CompositeHTTPPropagator
 ) and not any(
-    isinstance(p, DatadogFormat) for p in global_httptextformat._propagators
+    isinstance(p, DatadogFormat) for p in global_textmap._propagators
 ):
-    propagators.set_global_httptextformat(
+    propagators.set_global_textmap(
         propagators.composite.CompositeHTTPPropagator(
-            global_httptextformat._propagators + [DatadogFormat()]
+            global_textmap._propagators + [DatadogFormat()]
         )
     )
 else:
-    propagators.set_global_httptextformat(DatadogFormat())
+    propagators.set_global_textmap(DatadogFormat())
 
 tracer = trace.get_tracer(__name__)
 

docs/getting-started.rst

@@ -194,7 +194,7 @@ an example using Zipkin's `b3 propagation <https://github.com/openzipkin/b3-prop
     from opentelemetry import propagators
     from opentelemetry.sdk.trace.propagation.b3_format import B3Format
 
-    propagators.set_global_httptextformat(B3Format())
+    propagators.set_global_textmap(B3Format())
 
 
 Adding Metrics

exporter/opentelemetry-exporter-datadog/src/opentelemetry/exporter/datadog/__init__.py

@@ -50,7 +50,7 @@
     trace.get_tracer_provider().add_span_processor(span_processor)
 
     # Optional: use Datadog format for propagation in distributed traces
-    propagators.set_global_httptextformat(DatadogFormat())
+    propagators.set_global_textmap(DatadogFormat())
 
     with tracer.start_as_current_span("foo"):
         print("Hello world!")

exporter/opentelemetry-exporter-datadog/src/opentelemetry/exporter/datadog/propagator.py

@@ -17,18 +17,18 @@
 from opentelemetry import trace
 from opentelemetry.context import Context
 from opentelemetry.trace import get_current_span, set_span_in_context
-from opentelemetry.trace.propagation.httptextformat import (
+from opentelemetry.trace.propagation.textmap import (
     Getter,
-    HTTPTextFormat,
-    HTTPTextFormatT,
     Setter,
+    TextMapPropagator,
+    TextMapPropagatorT,
 )
 
 # pylint:disable=relative-beyond-top-level
 from . import constants
 
 
-class DatadogFormat(HTTPTextFormat):
+class DatadogFormat(TextMapPropagator):
     """Propagator for the Datadog HTTP header format.
     """
 
@@ -39,8 +39,8 @@ class DatadogFormat(HTTPTextFormat):
 
     def extract(
         self,
-        get_from_carrier: Getter[HTTPTextFormatT],
-        carrier: HTTPTextFormatT,
+        get_from_carrier: Getter[TextMapPropagatorT],
+        carrier: TextMapPropagatorT,
         context: typing.Optional[Context] = None,
     ) -> Context:
         trace_id = extract_first_element(
@@ -81,8 +81,8 @@ def extract(
 
     def inject(
         self,
-        set_in_carrier: Setter[HTTPTextFormatT],
-        carrier: HTTPTextFormatT,
+        set_in_carrier: Setter[TextMapPropagatorT],
+        carrier: TextMapPropagatorT,
         context: typing.Optional[Context] = None,
     ) -> None:
         span = get_current_span(context)
@@ -120,8 +120,8 @@ def format_span_id(span_id: int) -> str:
 
 
 def extract_first_element(
-    items: typing.Iterable[HTTPTextFormatT],
-) -> typing.Optional[HTTPTextFormatT]:
+    items: typing.Iterable[TextMapPropagatorT],
+) -> typing.Optional[TextMapPropagatorT]:
     if items is None:
         return None
     return next(iter(items), None)

instrumentation/opentelemetry-instrumentation-opentracing-shim/src/opentelemetry/instrumentation/opentracing_shim/__init__.py

@@ -676,7 +676,7 @@ def inject(self, span_context, format: object, carrier: object):
         if format not in self._supported_formats:
             raise UnsupportedFormatException
 
-        propagator = propagators.get_global_httptextformat()
+        propagator = propagators.get_global_textmap()
 
         ctx = set_span_in_context(DefaultSpan(span_context.unwrap()))
         propagator.inject(type(carrier).__setitem__, carrier, context=ctx)
@@ -710,7 +710,7 @@ def get_as_list(dict_object, key):
             value = dict_object.get(key)
             return [value] if value is not None else []
 
-        propagator = propagators.get_global_httptextformat()
+        propagator = propagators.get_global_textmap()
         ctx = propagator.extract(get_as_list, carrier)
         span = get_current_span(ctx)
         if span is not None:

instrumentation/opentelemetry-instrumentation-opentracing-shim/tests/test_shim.py

@@ -29,9 +29,9 @@
     util,
 )
 from opentelemetry.sdk.trace import TracerProvider
-from opentelemetry.test.mock_httptextformat import (
-    MockHTTPTextFormat,
-    NOOPHTTPTextFormat,
+from opentelemetry.test.mock_textmap import (
+    MockTextMapPropagator,
+    NOOPTextMapPropagator,
 )
 
 
@@ -46,15 +46,15 @@ def setUp(self):
     @classmethod
     def setUpClass(cls):
         # Save current propagator to be restored on teardown.
-        cls._previous_propagator = propagators.get_global_httptextformat()
+        cls._previous_propagator = propagators.get_global_textmap()
 
         # Set mock propagator for testing.
-        propagators.set_global_httptextformat(MockHTTPTextFormat())
+        propagators.set_global_textmap(MockTextMapPropagator())
 
     @classmethod
     def tearDownClass(cls):
         # Restore previous propagator.
-        propagators.set_global_httptextformat(cls._previous_propagator)
+        propagators.set_global_textmap(cls._previous_propagator)
 
     def test_shim_type(self):
         # Verify shim is an OpenTracing tracer.
@@ -482,8 +482,10 @@ def test_inject_http_headers(self):
 
         headers = {}
         self.shim.inject(context, opentracing.Format.HTTP_HEADERS, headers)
-        self.assertEqual(headers[MockHTTPTextFormat.TRACE_ID_KEY], str(1220))
-        self.assertEqual(headers[MockHTTPTextFormat.SPAN_ID_KEY], str(7478))
+        self.assertEqual(
+            headers[MockTextMapPropagator.TRACE_ID_KEY], str(1220)
+        )
+        self.assertEqual(headers[MockTextMapPropagator.SPAN_ID_KEY], str(7478))
 
     def test_inject_text_map(self):
         """Test `inject()` method for Format.TEXT_MAP."""
@@ -496,8 +498,12 @@ def test_inject_text_map(self):
         # Verify Format.TEXT_MAP
         text_map = {}
         self.shim.inject(context, opentracing.Format.TEXT_MAP, text_map)
-        self.assertEqual(text_map[MockHTTPTextFormat.TRACE_ID_KEY], str(1220))
-        self.assertEqual(text_map[MockHTTPTextFormat.SPAN_ID_KEY], str(7478))
+        self.assertEqual(
+            text_map[MockTextMapPropagator.TRACE_ID_KEY], str(1220)
+        )
+        self.assertEqual(
+            text_map[MockTextMapPropagator.SPAN_ID_KEY], str(7478)
+        )
 
     def test_inject_binary(self):
         """Test `inject()` method for Format.BINARY."""
@@ -515,8 +521,8 @@ def test_extract_http_headers(self):
         """Test `extract()` method for Format.HTTP_HEADERS."""
 
         carrier = {
-            MockHTTPTextFormat.TRACE_ID_KEY: 1220,
-            MockHTTPTextFormat.SPAN_ID_KEY: 7478,
+            MockTextMapPropagator.TRACE_ID_KEY: 1220,
+            MockTextMapPropagator.SPAN_ID_KEY: 7478,
         }
 
         ctx = self.shim.extract(opentracing.Format.HTTP_HEADERS, carrier)
@@ -527,22 +533,22 @@ def test_extract_empty_context_returns_invalid_context(self):
         """In the case where the propagator cannot extract a
         SpanContext, extract should return and invalid span context.
         """
-        _old_propagator = propagators.get_global_httptextformat()
-        propagators.set_global_httptextformat(NOOPHTTPTextFormat())
+        _old_propagator = propagators.get_global_textmap()
+        propagators.set_global_textmap(NOOPTextMapPropagator())
         try:
             carrier = {}
 
             ctx = self.shim.extract(opentracing.Format.HTTP_HEADERS, carrier)
             self.assertEqual(ctx.unwrap(), trace.INVALID_SPAN_CONTEXT)
         finally:
-            propagators.set_global_httptextformat(_old_propagator)
+            propagators.set_global_textmap(_old_propagator)
 
     def test_extract_text_map(self):
         """Test `extract()` method for Format.TEXT_MAP."""
 
         carrier = {
-            MockHTTPTextFormat.TRACE_ID_KEY: 1220,
-            MockHTTPTextFormat.SPAN_ID_KEY: 7478,
+            MockTextMapPropagator.TRACE_ID_KEY: 1220,
+            MockTextMapPropagator.SPAN_ID_KEY: 7478,
         }
 
         ctx = self.shim.extract(opentracing.Format.TEXT_MAP, carrier)

instrumentation/opentelemetry-instrumentation-requests/tests/test_requests_integration.py

@@ -22,7 +22,7 @@
 from opentelemetry import context, propagators, trace
 from opentelemetry.instrumentation.requests import RequestsInstrumentor
 from opentelemetry.sdk import resources
-from opentelemetry.test.mock_httptextformat import MockHTTPTextFormat
+from opentelemetry.test.mock_textmap import MockTextMapPropagator
 from opentelemetry.test.test_base import TestBase
 from opentelemetry.trace.status import StatusCanonicalCode
 
@@ -148,28 +148,28 @@ def test_suppress_instrumentation(self):
         self.assert_span(num_spans=0)
 
     def test_distributed_context(self):
-        previous_propagator = propagators.get_global_httptextformat()
+        previous_propagator = propagators.get_global_textmap()
         try:
-            propagators.set_global_httptextformat(MockHTTPTextFormat())
+            propagators.set_global_textmap(MockTextMapPropagator())
             result = self.perform_request(self.URL)
             self.assertEqual(result.text, "Hello!")
 
             span = self.assert_span()
 
             headers = dict(httpretty.last_request().headers)
-            self.assertIn(MockHTTPTextFormat.TRACE_ID_KEY, headers)
+            self.assertIn(MockTextMapPropagator.TRACE_ID_KEY, headers)
             self.assertEqual(
                 str(span.get_context().trace_id),
-                headers[MockHTTPTextFormat.TRACE_ID_KEY],
+                headers[MockTextMapPropagator.TRACE_ID_KEY],
             )
-            self.assertIn(MockHTTPTextFormat.SPAN_ID_KEY, headers)
+            self.assertIn(MockTextMapPropagator.SPAN_ID_KEY, headers)
             self.assertEqual(
                 str(span.get_context().span_id),
-                headers[MockHTTPTextFormat.SPAN_ID_KEY],
+                headers[MockTextMapPropagator.SPAN_ID_KEY],
             )
 
         finally:
-            propagators.set_global_httptextformat(previous_propagator)
+            propagators.set_global_textmap(previous_propagator)
 
     def test_span_callback(self):
         RequestsInstrumentor().uninstrument()

opentelemetry-api/CHANGELOG.md

@@ -14,6 +14,9 @@
   ([#1045](https://github.com/open-telemetry/opentelemetry-python/pull/1045))
 - Rename CorrelationContext to Baggage
   ([#1060](https://github.com/open-telemetry/opentelemetry-python/pull/1060))
+- Rename HTTPTextFormat to TextMapPropagator. This change also updates `get_global_httptextformat` and
+  `set_global_httptextformat` to `get_global_textmap` and `set_global_textmap`
+  ([#1085](https://github.com/open-telemetry/opentelemetry-python/pull/1085))
 
 ## Version 0.12b0
 

opentelemetry-api/src/opentelemetry/baggage/propagation/__init__.py

@@ -18,27 +18,25 @@
 from opentelemetry import baggage
 from opentelemetry.context import get_current
 from opentelemetry.context.context import Context
-from opentelemetry.trace.propagation import httptextformat
+from opentelemetry.trace.propagation import textmap
 
 
-class BaggagePropagator(httptextformat.HTTPTextFormat):
+class BaggagePropagator(textmap.TextMapPropagator):
     MAX_HEADER_LENGTH = 8192
     MAX_PAIR_LENGTH = 4096
     MAX_PAIRS = 180
     _BAGGAGE_HEADER_NAME = "otcorrelations"
 
     def extract(
         self,
-        get_from_carrier: httptextformat.Getter[
-            httptextformat.HTTPTextFormatT
-        ],
-        carrier: httptextformat.HTTPTextFormatT,
+        get_from_carrier: textmap.Getter[textmap.TextMapPropagatorT],
+        carrier: textmap.TextMapPropagatorT,
         context: typing.Optional[Context] = None,
     ) -> Context:
         """Extract Baggage from the carrier.
 
         See
-        `opentelemetry.trace.propagation.httptextformat.HTTPTextFormat.extract`
+        `opentelemetry.trace.propagation.textmap.TextMapPropagator.extract`
         """
 
         if context is None:
@@ -73,14 +71,14 @@ def extract(
 
     def inject(
         self,
-        set_in_carrier: httptextformat.Setter[httptextformat.HTTPTextFormatT],
-        carrier: httptextformat.HTTPTextFormatT,
+        set_in_carrier: textmap.Setter[textmap.TextMapPropagatorT],
+        carrier: textmap.TextMapPropagatorT,
         context: typing.Optional[Context] = None,
     ) -> None:
         """Injects Baggage into the carrier.
 
         See
-        `opentelemetry.trace.propagation.httptextformat.HTTPTextFormat.inject`
+        `opentelemetry.trace.propagation.textmap.TextMapPropagator.inject`
         """
         baggage_entries = baggage.get_all(context=context)
         if not baggage_entries:
@@ -100,8 +98,8 @@ def _format_baggage(baggage_entries: typing.Mapping[str, object]) -> str:
 
 
 def _extract_first_element(
-    items: typing.Iterable[httptextformat.HTTPTextFormatT],
-) -> typing.Optional[httptextformat.HTTPTextFormatT]:
+    items: typing.Iterable[textmap.TextMapPropagatorT],
+) -> typing.Optional[textmap.TextMapPropagatorT]:
     if items is None:
         return None
     return next(iter(items), None)