Authoring a propagator class

A Propagator class can help streamline integrations that require
extracting and injecting context.

Author: toumorokoshi

ext/opentelemetry-ext-http-requests/src/opentelemetry/ext/http_requests/__init__.py

@@ -21,6 +21,7 @@
 from urllib.parse import urlparse
 
 from requests.sessions import Session
+from opentelemetry import propagator
 
 
 # NOTE: Currently we force passing a tracer. But in turn, this forces the user
@@ -77,6 +78,10 @@ def instrumented_request(self, method, url, *args, **kwargs):
             span.set_attribute("http.status_code", result.status_code)
             span.set_attribute("http.status_text", result.reason)
 
+            propagator.global_propagator().inject(
+                result.headers.set, result.headers
+            )
+
             return result
 
         # TODO: How to handle exceptions? Should we create events for them? Set

ext/opentelemetry-ext-wsgi/src/opentelemetry/ext/wsgi/__init__.py

@@ -22,6 +22,7 @@
 import wsgiref.util as wsgiref_util
 
 from opentelemetry import trace
+from opentelemetry import propagator
 from opentelemetry.ext.wsgi.version import __version__  # noqa
 
 

opentelemetry-api/src/opentelemetry/propagator/__init__.py

@@ -0,0 +1,122 @@
+# Copyright 2019, OpenTelemetry Authors
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+import abc
+from opentelemetry import loader
+import opentelemetry.propagator.httptextformat as httptextformat
+import opentelemetry.propagator.binaryformat as binaryformat
+from opentelemetry.context import BaseRuntimeContext, Context
+
+
+class Propagator(abc.ABC):
+    """Class which encapsulates propagation of values to and from context.
+
+    In contract to using the formatters directly, a propagator object can
+    help own configuration around which formatters to use, as well as
+    help simplify the work require for integrations to use the intended
+    formatters.
+    """
+
+    def __init__(
+        self,
+        context: BaseRuntimeContext,
+        http_format: httptextformat.HTTPTextFormat,
+        binary_format: binaryformat.BinaryFormat,
+    ):
+        self._context = context
+        self._http_format = http_format
+        self._binary_format = binary_format
+
+    @classmethod
+    def create(
+        cls,
+        http_format: httptextformat.HTTPTextFormat,
+        binary_format: binaryformat.BinaryFormat,
+    ) -> "Propagator":
+        """Create a propagator with the current context."""
+        return Propagator(Context, http_format, binary_format)
+
+    @abc.abstractmethod
+    def extract(
+        self, get_from_carrier: httptextformat.Getter, carrier: object
+    ):
+        """Extract context data from the carrier, add to the context.
+
+        Using the http_format specified in the constructor, extract the
+        data form the carrier passed and add values into the context object.
+
+        Args:
+            get_from_carrier: a function that can retrieve zero
+                or more values from the carrier. In the case that
+                the value does not exist, return an empty list.
+            carrier: and object which contains values that are
+                used to construct a SpanContext. This object
+                must be paired with an appropriate get_from_carrier
+                which understands how to extract a value from it.
+        """
+
+    @abc.abstractmethod
+    def inject(
+        self, set_in_carrier: httptextformat.Setter, carrier: object
+    ) -> None:
+        """Inject values from context into a carrier.
+
+        inject enables the propagation of values into HTTP clients or
+        other objects which perform an HTTP request. Using the
+        httptextformat configured, inject the context data into
+        the carrier with the set_in_carrier method passed.
+
+        Args:
+            set_in_carrier: A setter function that can set values
+                on the carrier.
+            carrier: An object that a place to define HTTP headers.
+                Should be paired with set_in_carrier, which should
+                know how to set header values on the carrier.
+        """
+
+    @abc.abstractmethod
+    def from_bytes(self, byte_representation: bytes) -> None:
+        """Populate context with data that existed in the byte representation.
+
+        Using the configured binary_format, extract values from the bytes object
+        passed into the context object configured.
+
+        Args:
+            byte_representation: the bytes to deserialize.
+        """
+
+    @abc.abstractmethod
+    def to_bytes(self) -> bytes:
+        """Creates a byte representation of the context configured.
+
+        to_bytes should read values from the configured context and 
+        return a bytes object to represent it.
+
+        Returns:
+            A bytes representation of the DistributedContext.
+        """
+
+
+def set_propagator(propagator_instance: Propagator) -> None:
+    """Set the propagator instance singleton.
+    """
+    global _PROPAGATOR
+    _PROPAGATOR = propagator_instance
+
+
+def global_propagator() -> Propagator:
+    """Return the singleton propagator instance."""
+    return _PROPAGATOR
+
+
+_PROPAGATOR = None  # type: typing.Optional[Propagator]

opentelemetry-api/src/opentelemetry/propagator/binaryformat.py

@@ -45,7 +45,7 @@ def to_bytes(context: BaseRuntimeContext) -> bytes:
     def from_bytes(
         context: BaseRuntimeContext, byte_representation: bytes
     ) -> None:
-        """Populate context with context data that existed in the byte representation.
+        """Populate context with data that existed in the byte representation.
 
         from_bytes should add values into the context from the data serialized in the
         byte_representation passed. If it is not possible to read in a proper

opentelemetry-sdk/src/opentelemetry/sdk/propagator/__init__.py

@@ -0,0 +1,15 @@
+from opentelemetry.propagator import Propagator as PropagatorAPI
+
+
+class Propagator(PropagatorAPI):
+    def extract(self, get_from_carrier, carrier):
+        self.http_format.extract(self.context, get_from_carrier, carrier)
+
+    def inject(self, set_in_carrier, carrier):
+        self.http_format.inject(self.context, set_in_carrier, carrier)
+
+    def from_bytes(self, byte_representation):
+        self.binary_formatter.from_bytes(self.context, byte_representation)
+
+    def to_bytes(self):
+        return self.binary_formatter.to_bytes(self.context)