Distributed Tracing
This document describes how an SDK should propagate information between different services to connect all telemetry (errors, profiles, replays, transaction, check-ins, ...) from those services into one trace.
For an overview see Distributed Tracing in the product docs.
Sentry uses three containers to hold trace information sentry-trace
, baggage
and optionally traceparent
.
With these containers you can propagate a trace to a down-stream service by either:
- adding
sentry-trace
andbaggage
HTTP headers (when making outgoing HTTP requests), - adding
sentry-trace
andbaggage
as meta data (when putting tasks into a queue, details are specific to the queue you want to support), or - setting environment variables (when calling another process). In this case the env variables should be called
SENTRY_TRACE
andSENTRY_BAGGAGE
.
The SDK running in the receiving service needs to make sure to pick up incoming trace information by
- reading
sentry-trace
andbaggage
headers for each incoming HTTP request, - reading
sentry-trace
andbaggage
meta data when retrieving an item from a queue, or - reading the environment variables
SENTRY_TRACE
andSENTRY_BAGGAGE
on startup.
This trace information should be stored in the "propagation context" of the current scope. This makes sure that all telemetry that is emitted from the receiving service to Sentry will include the correct trace information.
To interoperate with OpenTelemetry (OTel) services, SDKs can optionally send the W3C Trace Context traceparent
HTTP header on outgoing requests in addition to Sentry’s own sentry-trace
and baggage
. This enables traces originating from a Sentry SDK to be continued by components that only use OTel/W3C propagation.
The traceparent
header must only be sent when propagateTraceparent
is true
and the request matches tracePropagationTargets
(same condition as for sentry-trace
/baggage
).
The full spec is available in the W3C Trace Context document.
Our documentation is open source and available on GitHub. Your contributions are welcome, whether fixing a typo (drat!) or suggesting an update ("yeah, this would be better").