|
| 1 | +--- |
| 2 | +title: Tracing Without Performance |
| 3 | +--- |
| 4 | + |
| 5 | +If Sentry SDKs are not configured for sending spans (or transactions), they should fall back to a mode where they still handle continuing and propagating traces. |
| 6 | +Internally, we call this mode "Tracing without Performance", or "TwP" in short ([learn more why](#historical-context)). |
| 7 | +TwP mode ensures that error events and other signals are still connected via a trace, even if users choose not to send spans or performance data. |
| 8 | + |
| 9 | +## Behavior |
| 10 | + |
| 11 | +Tracing without Performance is the default fallback behavior of SDKs, when users [don't specify any tracing options](#configuration). |
| 12 | + |
| 13 | +This means that SDKs by default always: |
| 14 | + |
| 15 | +- continue incoming traces |
| 16 | +- attach `event.contexts.trace` context on events (e.g. errors, check-ins, replays) |
| 17 | +- attach the `trace` envelope header to Sentry envelopes, populated from the dynamic sampling context |
| 18 | +- propagate trace data (`sentry-trace`, `baggage`) via the usual channels (e.g. HTTP headers, `<meta>` HTML elements, etc), with the correct [sampling decision](#sampling-decision) |
| 19 | + |
| 20 | +## Configuration |
| 21 | + |
| 22 | +TwP is active by default if users don't specify sampling options that enable span collection and sending (i.e. [regular tracing](#enable-regular-tracing)). |
| 23 | +For example, the following trivial SDK setup (note the absence of sampling options) enables TwP: |
| 24 | + |
| 25 | +```JavaScript |
| 26 | +Sentry.init({ |
| 27 | + dsn: "___PUBLIC_DSN___", |
| 28 | +}); |
| 29 | +``` |
| 30 | + |
| 31 | +TwP mode is exited by configuring the SDK for [regular tracing](#enable-regular-tracing) or partially disabled by [opting out of trace propagation](#disable-trace-propagation). |
| 32 | + |
| 33 | +<Alert> |
| 34 | + |
| 35 | +Note that some SDKs like the JavaScript Browser SDK require additional integrations to enable tracing all together. |
| 36 | +This is fine as long as there's a good reason why additional configuration is required (like keeping bundle size in check in JS). |
| 37 | + |
| 38 | +</Alert> |
| 39 | + |
| 40 | +### Enable Regular Tracing |
| 41 | + |
| 42 | +As soon as users specify a tracing option in the SDK configuration, SDKs will use the normal tracing mode, which means collecting and sending spans (or transactions) in addition to continuing and propagating traces. |
| 43 | + |
| 44 | +This can be achieved by specifying `tracesSampleRate` or `tracesSampler`, or any other equivalent option in the SDK configuration: |
| 45 | + |
| 46 | +```js |
| 47 | +Sentry.init({ |
| 48 | + dsn: "___PUBLIC_DSN___", |
| 49 | + tracesSampleRate: 0.1, |
| 50 | + // or |
| 51 | + tracesSampler: () => { |
| 52 | + /*...*/ |
| 53 | + }, |
| 54 | +}); |
| 55 | +``` |
| 56 | + |
| 57 | +It's important to note that setting `tracesSampleRate: 0` does not mean that we fall back to TwP mode but that sampling decisions are always negative and we propagate the trace with a negative sampling decision. |
| 58 | + |
| 59 | +### Disable Trace Propagation |
| 60 | + |
| 61 | +To opt out of further propagating a trace, users can pass an empty array (or language-equivalent parameter) to the [`tracePropagationTargets` option](/sdk/telemetry/traces/#tracepropagationtargets). This will prevent the SDK from propagating trace information any further. |
| 62 | + |
| 63 | +```js |
| 64 | +Sentry.init({ |
| 65 | + dsn: "___PUBLIC_DSN___", |
| 66 | + tracePropagationTargets: [], |
| 67 | +}); |
| 68 | +``` |
| 69 | + |
| 70 | +Note, that for incoming requests with trace headers, SDKs should still continue this trace, but not propagate it further downstream. |
| 71 | + |
| 72 | +## Implementation |
| 73 | + |
| 74 | +SDKs implementing TwP mode must adhere to the behavior described in this section. |
| 75 | +Everything else (e.g. how to store the trace data and specific tracing options) is considered an implementation detail and can be implemented as needed. |
| 76 | + |
| 77 | +### Continuing Incoming Traces |
| 78 | + |
| 79 | +SDKs in TwP mode must continue incoming traces (e.g. from incoming HTTP requests) if available and attach the trace data of the continued trace to any events that are created during the lifetime of this trace. |
| 80 | +Furthermore, they must propagate the continued trace as usual on all outgoing requests. |
| 81 | +This means that continuing traces should work just like in the regular tracing mode (with spans). |
| 82 | + |
| 83 | +At the time of writing this document, there is no way to opt out of continuing incoming traces in TwP mode, unless users manually start a new trace. |
| 84 | + |
| 85 | +### Starting a New Trace |
| 86 | + |
| 87 | +If an SDK in TwP mode doesn't receive an incoming trace, it should start a new trace. |
| 88 | +In this case, the new trace is not sampled (as in, there is no sampling decision, neither positive nor negative). |
| 89 | +Instead, the sampling decision is _deferred_ to the next downstream SDK. |
| 90 | + |
| 91 | +This means that: |
| 92 | + |
| 93 | +- the SDK must not include a sampled flag in the [`sentry-trace` header](../#header-sentry-trace), meaning the header has the format `<traceId>-<spanId>`. |
| 94 | + More details on the [sampled flag](../#the-sampled-value). |
| 95 | +- the [dynamic sampling context](https://develop.sentry.dev/sdk/telemetry/traces/dynamic-sampling-context/), propagated via `baggage` must not contain the `sentry-sampled` key. |
| 96 | + |
| 97 | +### Attaching Trace Data to Events and Envelopes |
| 98 | + |
| 99 | +Any event created by an SDK in TwP mode must include the [`trace` context](/sdk/event-payloads/contexts/#trace-context). |
| 100 | +This context should contain the trace data of the current trace, if available, just like in regular tracing mode. |
| 101 | + |
| 102 | +Furthermore, the [`trace` envelope header](/sdk/telemetry/traces/dynamic-sampling-context/#envelope-header) (populated from the dynamic sampling context) must be attached to any outgoing event envelope. |
| 103 | + |
| 104 | +### Trace Duration and Storage |
| 105 | + |
| 106 | +Traces in TwP mode should have the same duration as regular traces. |
| 107 | +For example, a TwP trace for a backend server should generally last for the duration of one individual request. |
| 108 | +This usually corresponds with the lifetime of an [isolation scope](/sdk/miscellaneous/hub_and_scope_refactoring/#scope) (or current scope created within the isolation scope). |
| 109 | + |
| 110 | +SDKs in TwP mode must store trace data in a way that makes it possible for them to be attached to events and propagated to outgoing requests. |
| 111 | +The exact storage mechanism is up to the SDK implementation, but we recommended using the same mechanism as for regular traces. |
| 112 | +Usually this means storing the data on the scope in a field called `propagationContext` as [recommended here](/sdk/telemetry/traces/distributed-tracing/). |
| 113 | + |
| 114 | +On a related note, the `propagationContext` should be populated with a random `traceId` and `spanId` if no incoming trace is present. |
| 115 | +This—in combination with the [`sentry-trace` header specification](/sdk/telemetry/traces/#header-sentry-trace) requiring a `spanId`—has an important implication on the Sentry product: |
| 116 | +A non-existing `spanId` will be propagated along with the trace and attached to events. |
| 117 | +While not ideal, we accept this limitation as the Sentry product can and should handle non-existing (parent) spans anyway. |
| 118 | + |
| 119 | +As in regular tracing mode, for SDKs starting a new trace, the [Dynamic Sampling Context](/sdk/telemetry/traces/dynamic-sampling-context/) should be lazily populated and frozen for the duration of the trace. |
| 120 | +Given that no span is actually available in TwP mode, the DSC will not contain any keys related to spans (`transaction`, `sample_rate` or `sampled`). |
| 121 | + |
| 122 | +In SDKs adapting OpenTelemetry's tracing capabilities ([POTel](/sdk/hub_and_scope_refactoring/#f-use-otel-for-performance-instrumentation-potel)), the TwP trace data could also be stored in a non-recording span. |
| 123 | +For Example, the Node SDK also starts non-recording Otel spans in TwP mode and takes the trace data from them. In case no span is started (e.g. a node script without request handling), it falls back to the propagation context on the scope. |
| 124 | +Note that in the case of using the non-recording span, the span is also not sampled, meaning the sampling decision must still be deferred [when starting a new Trace](#starting-a-new-trace). |
| 125 | + |
| 126 | +## Historical Context |
| 127 | + |
| 128 | +TwP mode was introduced after SDKs were already capable of sending spans and transactions. Before TwP, SDKs would only handle traces if span-sending was enabled. Otherwise, neither trace data would be attached to any events nor were traces propagated further downstream. |
| 129 | + |
| 130 | +The primary motivation for TwP was to ensure that errors across application or service boundaries were still connected if they occurred in the same trace. |
| 131 | + |
| 132 | +The name "Tracing without Performance" was chosen because at the time of introduction, we associated spans purely with performance monitoring. |
| 133 | +Today, we associate spans with "Tracing" in general, and only (some of) the data from spans with Performance Monitoring. |
| 134 | +This is why the name from today's perspective is a bit misleading. |
| 135 | +As a mental model, think of TwP as "Trace propagation and continuation without Spans". |
0 commit comments