Span Trace Propagation
🚧 This document is work in progress.
This document uses key words such as "MUST", "SHOULD", and "MAY" as defined in RFC 2119 to indicate requirement levels.
To continue a trace from an upstream service, the SDK must expose a method to extract the traceparent and baggage information and apply these to the applicable scope. The method MUST NOT create a new segment span on its own.
Sentry.continueTrace({
sentryTrace: request.headers['sentry-trace'],
baggage: request.headers['baggage'],
}, () => {
Sentry.startSpan({ name: 'test' }, () => {
// ....
});
})
Sentry.continueTrace({
sentryTrace: request.headers['sentry-trace'],
baggage: request.headers['baggage'],
}, () => {
Sentry.startSpan({ name: 'test' }, () => {
// ....
});
})
sentry_sdk.continue_trace(request.headers)
with sentry_sdk.start_span(name="test"):
...
Newly created root spans should now contain these properties, such as trace_id and parent_span_id.
The exact function signature of the continueTrace function depends on what's canonical in your SDK. It MAY require explicitly passing sentry-trace and baggage, or it MAY allow providing a dictionary of headers/environment variables.
To propagate a trace to a downstream service, the SDK MUST expose methods to fetch the required information to allow the next service to continue the trace.
const traceData = Sentry.getTraceData()
const traceData = Sentry.getTraceData()
traceparent = sentry_sdk.get_traceparent()
baggage = sentry_sdk.get_baggage()
The SDK MUST offer a method to clear trace propagation data, allowing to create spans with a fresh new trace.
Sentry.startNewTrace(() => {
Sentry.startSpan({ name: 'segment under trace 1' }, () => {...});
})
Sentry.startNewTrace(() => {
Sentry.startSpan({ name: 'segment under trace 2' }, () => {...});
})
Sentry.startNewTrace(() => {
Sentry.startSpan({ name: 'segment under trace 1' }, () => {...});
})
Sentry.startNewTrace(() => {
Sentry.startSpan({ name: 'segment under trace 2' }, () => {...});
})
import sentry_sdk
with sentry_sdk.start_span(name="segment under trace 1"):
...
sentry_sdk.new_trace()
# The next span started after new_trace() will NOT continue the same trace:
with sentry_sdk.start_span(name="segment under trace 2"):
...
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").