From 2f8c19058b058648d33dc738c2dca3b980895eb9 Mon Sep 17 00:00:00 2001 From: Owais Lone Date: Mon, 12 Apr 2021 19:10:23 +0530 Subject: [PATCH 1/2] Added experimental HTTP backpropagators The experimental back propagators inject trace response headers into HTTP responses. These are meant to be used by instrumentations and are not considered stable. --- CHANGELOG.md | 2 + .../instrumentation/propagators.py | 104 ++++++++++++++++++ .../tests/test_propagators.py | 80 ++++++++++++++ 3 files changed, 186 insertions(+) create mode 100644 opentelemetry-instrumentation/src/opentelemetry/instrumentation/propagators.py create mode 100644 opentelemetry-instrumentation/tests/test_propagators.py diff --git a/CHANGELOG.md b/CHANGELOG.md index ebfb94a195e..0ce882b471f 100644 --- a/CHANGELOG.md +++ b/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 diff --git a/opentelemetry-instrumentation/src/opentelemetry/instrumentation/propagators.py b/opentelemetry-instrumentation/src/opentelemetry/instrumentation/propagators.py new file mode 100644 index 00000000000..753da42aa5c --- /dev/null +++ b/opentelemetry-instrumentation/src/opentelemetry/instrumentation/propagators.py @@ -0,0 +1,104 @@ +# 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 response context +into HTTP responses. 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 DictHeaderSetter: + 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 + + +default_setter = DictHeaderSetter() + + +class FuncSetter: + def __init__(self, func): + self._func = func + + def set(self, carrier, key, value): + self._func(carrier, key, value) + + +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, + ) diff --git a/opentelemetry-instrumentation/tests/test_propagators.py b/opentelemetry-instrumentation/tests/test_propagators.py new file mode 100644 index 00000000000..62461aafa97 --- /dev/null +++ b/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", + ) From 8565c64d1050c93be8b4aef39bd7684432c95fdb Mon Sep 17 00:00:00 2001 From: Owais Lone Date: Sat, 17 Apr 2021 00:05:03 +0530 Subject: [PATCH 2/2] Update opentelemetry-instrumentation/src/opentelemetry/instrumentation/propagators.py --- .../instrumentation/propagators.py | 36 +++++++++++++++---- 1 file changed, 30 insertions(+), 6 deletions(-) diff --git a/opentelemetry-instrumentation/src/opentelemetry/instrumentation/propagators.py b/opentelemetry-instrumentation/src/opentelemetry/instrumentation/propagators.py index 753da42aa5c..2fb246c9d95 100644 --- a/opentelemetry-instrumentation/src/opentelemetry/instrumentation/propagators.py +++ b/opentelemetry-instrumentation/src/opentelemetry/instrumentation/propagators.py @@ -13,8 +13,8 @@ # limitations under the License. """ -This module implements experimental propagators to inject trace response context -into HTTP responses. This is useful for server side frameworks that start traces +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. @@ -44,7 +44,13 @@ def set_global_response_propagator(propagator): _RESPONSE_PROPAGATOR = propagator -class DictHeaderSetter: +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: @@ -52,10 +58,23 @@ def set(self, carrier, key, value): # pylint: disable=no-self-use carrier[key] = value -default_setter = DictHeaderSetter() +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)` + """ -class FuncSetter: def __init__(self, func): self._func = func @@ -63,6 +82,9 @@ def set(self, carrier, key, value): self._func(carrier, key, value) +default_setter = DictHeaderSetter() + + class ResponsePropagator(ABC): @abstractmethod def inject( @@ -100,5 +122,7 @@ def inject( ), ) setter.set( - carrier, _HTTP_HEADER_ACCESS_CONTROL_EXPOSE_HEADERS, header_name, + carrier, + _HTTP_HEADER_ACCESS_CONTROL_EXPOSE_HEADERS, + header_name, )