Added experimental HTTP backpropagators

CHANGELOG.md

@@ -13,6 +13,8 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 - Added `SpanKind` to `should_sample` parameters, suggest using parent span context's tracestate
   instead of manually passed in tracestate in `should_sample`
   ([#1764](https://github.com/open-telemetry/opentelemetry-python/pull/1764))
+- Added experimental HTTP back propagators.
+  ([#1762](https://github.com/open-telemetry/opentelemetry-python/pull/1762))
 
 ### Changed
 - Adjust `B3Format` propagator to be spec compliant by not modifying context

opentelemetry-instrumentation/src/opentelemetry/instrumentation/propagators.py

@@ -0,0 +1,128 @@
+# Copyright The 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.
+
+"""
+This module implements experimental propagators to inject trace context
+into response carriers. This is useful for server side frameworks that start traces
+when server requests and want to share the trace context with the client so the
+client can add it's spans to the same trace.
+
+This is part of an upcoming W3C spec and will eventually make it to the Otel spec.
+
+https://w3c.github.io/trace-context/#trace-context-http-response-headers-format
+"""
+
+import typing
+from abc import ABC, abstractmethod
+
+import opentelemetry.trace as trace
+from opentelemetry.context.context import Context
+from opentelemetry.propagators import textmap
+from opentelemetry.trace import format_span_id, format_trace_id
+
+_HTTP_HEADER_ACCESS_CONTROL_EXPOSE_HEADERS = "Access-Control-Expose-Headers"
+_RESPONSE_PROPAGATOR = None
+
+
+def get_global_response_propagator():
+    return _RESPONSE_PROPAGATOR
+
+
+def set_global_response_propagator(propagator):
+    global _RESPONSE_PROPAGATOR  # pylint:disable=global-statement
+    _RESPONSE_PROPAGATOR = propagator
+
+
+class Setter(ABC):
+    @abstractmethod
+    def set(self, carrier, key, value):
+        """Inject the provided key value pair in carrier."""
+
+
+class DictHeaderSetter(Setter):
+    def set(self, carrier, key, value):  # pylint: disable=no-self-use
+        old_value = carrier.get(key, "")
+        if old_value:
+            value = "{0}, {1}".format(old_value, value)
+        carrier[key] = value
+
+
+class FuncSetter(Setter):
+    """FuncSetter coverts a function into a valid Setter. Any function that can
+    set values in a carrier can be converted into a Setter by using FuncSetter.
+    This is useful when injecting trace context into non-dict objects such
+    HTTP Response objects for different framework.
+
+    For example, it can be used to create a setter for Falcon response object as:
+
+        setter = FuncSetter(falcon.api.Response.append_header)
+
+    and then used with the propagator as:
+
+        propagator.inject(falcon_response, setter=setter)
+
+    This would essentially make the propagator call `falcon_response.append_header(key, value)`
+    """
+
+    def __init__(self, func):
+        self._func = func
+
+    def set(self, carrier, key, value):
+        self._func(carrier, key, value)
+
+
+default_setter = DictHeaderSetter()
+
+
+class ResponsePropagator(ABC):
+    @abstractmethod
+    def inject(
+        self,
+        carrier: textmap.CarrierT,
+        context: typing.Optional[Context] = None,
+        setter: textmap.Setter = default_setter,
+    ) -> None:
+        """Injects SpanContext into the HTTP response carrier."""
+
+
+class TraceResponsePropagator(ResponsePropagator):
+    """Experimental propagator that injects tracecontext into HTTP responses."""
+
+    def inject(
+        self,
+        carrier: textmap.CarrierT,
+        context: typing.Optional[Context] = None,
+        setter: textmap.Setter = default_setter,
+    ) -> None:
+        """Injects SpanContext into the HTTP response carrier."""
+        span = trace.get_current_span(context)
+        span_context = span.get_span_context()
+        if span_context == trace.INVALID_SPAN_CONTEXT:
+            return
+
+        header_name = "traceresponse"
+        setter.set(
+            carrier,
+            header_name,
+            "00-{trace_id}-{span_id}-{:02x}".format(
+                span_context.trace_flags,
+                trace_id=format_trace_id(span_context.trace_id),
+                span_id=format_span_id(span_context.span_id),
+            ),
+        )
+        setter.set(
+            carrier,
+            _HTTP_HEADER_ACCESS_CONTROL_EXPOSE_HEADERS,
+            header_name,
+        )

opentelemetry-instrumentation/tests/test_propagators.py

@@ -0,0 +1,80 @@
+# Copyright The 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.
+
+# pylint: disable=protected-access
+
+from opentelemetry import trace
+from opentelemetry.instrumentation import propagators
+from opentelemetry.instrumentation.propagators import (
+    DictHeaderSetter,
+    TraceResponsePropagator,
+    get_global_response_propagator,
+    set_global_response_propagator,
+)
+from opentelemetry.test.test_base import TestBase
+
+
+class TestGlobals(TestBase):
+    def test_get_set(self):
+        original = propagators._RESPONSE_PROPAGATOR
+
+        propagators._RESPONSE_PROPAGATOR = None
+        self.assertIsNone(get_global_response_propagator())
+
+        prop = TraceResponsePropagator()
+        set_global_response_propagator(prop)
+        self.assertIs(prop, get_global_response_propagator())
+
+        propagators._RESPONSE_PROPAGATOR = original
+
+
+class TestDictHeaderSetter(TestBase):
+    def test_simple(self):
+        setter = DictHeaderSetter()
+        carrier = {}
+        setter.set(carrier, "kk", "vv")
+        self.assertIn("kk", carrier)
+        self.assertEqual(carrier["kk"], "vv")
+
+    def test_append(self):
+        setter = DictHeaderSetter()
+        carrier = {"kk": "old"}
+        setter.set(carrier, "kk", "vv")
+        self.assertIn("kk", carrier)
+        self.assertEqual(carrier["kk"], "old, vv")
+
+
+class TestTraceResponsePropagator(TestBase):
+    def test_inject(self):
+        span = trace.NonRecordingSpan(
+            trace.SpanContext(
+                trace_id=1,
+                span_id=2,
+                is_remote=False,
+                trace_flags=trace.DEFAULT_TRACE_OPTIONS,
+                trace_state=trace.DEFAULT_TRACE_STATE,
+            ),
+        )
+
+        ctx = trace.set_span_in_context(span)
+        prop = TraceResponsePropagator()
+        carrier = {}
+        prop.inject(carrier, ctx)
+        self.assertEqual(
+            carrier["Access-Control-Expose-Headers"], "traceresponse"
+        )
+        self.assertEqual(
+            carrier["traceresponse"],
+            "00-00000000000000000000000000000001-0000000000000002-00",
+        )