feat(tracing): Add tracestate header handling (#1179)

This introduces handling of the `tracestate` header, as described in the W3C Trace Context spec[1] and our own corresponding spec[2].

 Key features:

- Deprecation of `from_traceparent` in favor of `continue_from_headers`, which now propagates both incoming `sentry-trace` and incoming `tracestate` headers.
- Propagation of `tracestate` value as a header on outgoing HTTP requests when they're made during a transaction.
- Addition of `tracestate` data to transaction envelope headers.

Supporting changes:

- New utility methods for converting strings to and from base64.
- Some refactoring vis-à-vis the links between transactions, span recorders, and spans. See #1173 and #1184.
- Moving of some tracing code to a separate `tracing_utils` file.

Note: `tracestate` handling  is currently feature-gated by the flag `propagate_tracestate` in the `_experiments` SDK option. 

More details can be found in the main PR on this branch, #971.

[1] https://www.w3.org/TR/trace-context/#tracestate-header
[2] https://develop.sentry.dev/sdk/performance/trace-context/

Author: lobsterkatie

sentry_sdk/client.py

@@ -22,6 +22,7 @@
 from sentry_sdk.utils import ContextVar
 from sentry_sdk.sessions import SessionFlusher
 from sentry_sdk.envelope import Envelope
+from sentry_sdk.tracing_utils import has_tracestate_enabled, reinflate_tracestate
 
 from sentry_sdk._types import MYPY
 
@@ -332,15 +333,29 @@ def capture_event(
         attachments = hint.get("attachments")
         is_transaction = event_opt.get("type") == "transaction"
 
+        # this is outside of the `if` immediately below because even if we don't
+        # use the value, we want to make sure we remove it before the event is
+        # sent
+        raw_tracestate = (
+            event_opt.get("contexts", {}).get("trace", {}).pop("tracestate", "")
+        )
+
+        # Transactions or events with attachments should go to the /envelope/
+        # endpoint.
         if is_transaction or attachments:
-            # Transactions or events with attachments should go to the
-            # /envelope/ endpoint.
-            envelope = Envelope(
-                headers={
-                    "event_id": event_opt["event_id"],
-                    "sent_at": format_timestamp(datetime.utcnow()),
-                }
+
+            headers = {
+                "event_id": event_opt["event_id"],
+                "sent_at": format_timestamp(datetime.utcnow()),
+            }
+
+            tracestate_data = raw_tracestate and reinflate_tracestate(
+                raw_tracestate.replace("sentry=", "")
             )
+            if tracestate_data and has_tracestate_enabled():
+                headers["trace"] = tracestate_data
+
+            envelope = Envelope(headers=headers)
 
             if is_transaction:
                 envelope.add_transaction(event_opt)

sentry_sdk/consts.py

@@ -32,6 +32,7 @@
             "max_spans": Optional[int],
             "record_sql_params": Optional[bool],
             "smart_transaction_trimming": Optional[bool],
+            "propagate_tracestate": Optional[bool],
         },
         total=False,
     )

sentry_sdk/hub.py

@@ -700,7 +700,8 @@ def iter_trace_propagation_headers(self, span=None):
         if not propagate_traces:
             return
 
-        yield "sentry-trace", span.to_traceparent()
+        for header in span.iter_headers():
+            yield header
 
 
 GLOBAL_HUB = Hub()

sentry_sdk/integrations/django/__init__.py

@@ -9,7 +9,7 @@
 from sentry_sdk.hub import Hub, _should_send_default_pii
 from sentry_sdk.scope import add_global_event_processor
 from sentry_sdk.serializer import add_global_repr_processor
-from sentry_sdk.tracing import record_sql_queries
+from sentry_sdk.tracing_utils import record_sql_queries
 from sentry_sdk.utils import (
     HAS_REAL_CONTEXTVARS,
     CONTEXTVARS_ERROR_MESSAGE,

sentry_sdk/integrations/httpx.py

@@ -1,5 +1,6 @@
 from sentry_sdk import Hub
 from sentry_sdk.integrations import Integration, DidNotEnable
+from sentry_sdk.utils import logger
 
 from sentry_sdk._types import MYPY
 
@@ -45,6 +46,11 @@ def send(self, request, **kwargs):
             span.set_data("method", request.method)
             span.set_data("url", str(request.url))
             for key, value in hub.iter_trace_propagation_headers():
+                logger.debug(
+                    "[Tracing] Adding `{key}` header {value} to outgoing request to {url}.".format(
+                        key=key, value=value, url=request.url
+                    )
+                )
                 request.headers[key] = value
             rv = real_send(self, request, **kwargs)
 
@@ -72,6 +78,11 @@ async def send(self, request, **kwargs):
             span.set_data("method", request.method)
             span.set_data("url", str(request.url))
             for key, value in hub.iter_trace_propagation_headers():
+                logger.debug(
+                    "[Tracing] Adding `{key}` header {value} to outgoing request to {url}.".format(
+                        key=key, value=value, url=request.url
+                    )
+                )
                 request.headers[key] = value
             rv = await real_send(self, request, **kwargs)
 

sentry_sdk/integrations/sqlalchemy.py

@@ -3,7 +3,7 @@
 from sentry_sdk._types import MYPY
 from sentry_sdk.hub import Hub
 from sentry_sdk.integrations import Integration, DidNotEnable
-from sentry_sdk.tracing import record_sql_queries
+from sentry_sdk.tracing_utils import record_sql_queries
 
 try:
     from sqlalchemy.engine import Engine  # type: ignore

sentry_sdk/integrations/stdlib.py

@@ -6,8 +6,8 @@
 from sentry_sdk.hub import Hub
 from sentry_sdk.integrations import Integration
 from sentry_sdk.scope import add_global_event_processor
-from sentry_sdk.tracing import EnvironHeaders
-from sentry_sdk.utils import capture_internal_exceptions, safe_repr
+from sentry_sdk.tracing_utils import EnvironHeaders
+from sentry_sdk.utils import capture_internal_exceptions, logger, safe_repr
 
 from sentry_sdk._types import MYPY
 
@@ -86,6 +86,11 @@ def putrequest(self, method, url, *args, **kwargs):
         rv = real_putrequest(self, method, url, *args, **kwargs)
 
         for key, value in hub.iter_trace_propagation_headers(span):
+            logger.debug(
+                "[Tracing] Adding `{key}` header {value} to outgoing request to {real_url}.".format(
+                    key=key, value=value, real_url=real_url
+                )
+            )
             self.putheader(key, value)
 
         self._sentrysdk_span = span

sentry_sdk/scope.py

@@ -150,19 +150,13 @@ def transaction(self):
         if self._span is None:
             return None
 
-        # the span on the scope is itself a transaction
-        if isinstance(self._span, Transaction):
-            return self._span
-
-        # the span on the scope isn't a transaction but belongs to one
-        if self._span._containing_transaction:
-            return self._span._containing_transaction
+        # there is an orphan span on the scope
+        if self._span.containing_transaction is None:
+            return None
 
-        # there's a span (not a transaction) on the scope, but it was started on
-        # its own, not as the descendant of a transaction (this is deprecated
-        # behavior, but as long as the start_span function exists, it can still
-        # happen)
-        return None
+        # there is either a transaction (which is its own containing
+        # transaction) or a non-orphan span on the scope
+        return self._span.containing_transaction
 
     @transaction.setter
     def transaction(self, value):
@@ -174,7 +168,7 @@ def transaction(self, value):
         # anything set in the scope.
         # XXX: note that with the introduction of the Scope.transaction getter,
         # there is a semantic and type mismatch between getter and setter. The
-        # getter returns a transaction, the setter sets a transaction name.
+        # getter returns a Transaction, the setter sets a transaction name.
         # Without breaking version compatibility, we could make the setter set a
         # transaction name or transaction (self._span) depending on the type of
         # the value argument.