You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Copy file name to clipboardExpand all lines: develop-docs/sdk/telemetry/traces/tracing-without-performance.mdx
+20-19Lines changed: 20 additions & 19 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -2,26 +2,24 @@
2
2
title: Tracing Without Performance
3
3
---
4
4
5
-
If Sentry SDKs are not configured for sending spans (or transactions), they should fall back to a mode where they still handle attaching and propagating trace data.
6
-
Internally, we call this mode "Tracing without Performance" (or "TwP" in short).
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
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
8
9
-
## Outcome
9
+
## Behavior
10
10
11
11
Tracing without Performance is the default fallback behavior of SDKs, when users [don't specify any tracing options](#configuration).
12
12
13
-
This means that SDKs in this mode always:
13
+
This means that SDKs by default always:
14
14
15
15
- continue incoming traces
16
-
- attach `event.contexts.trace` context on events (e.g. errors, check-ins)
16
+
- attach `event.contexts.trace` context on events (e.g. errors, check-ins, replays)
17
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 tags`, etc), with the correct [sampling decision](#sampling-decision)
19
-
20
-
If users [explicitly opt out](#completely-disable-tracing) of all tracing capabilities, TwP mode will no longer be active.
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)
21
19
22
20
## Configuration
23
21
24
-
TwP is active by default if users don't specify sampling options that enable span collection and sending.
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)).
25
23
For example, the following trivial SDK setup (note the absence of sampling options) enables TwP:
26
24
27
25
```JavaScript
@@ -30,7 +28,7 @@ Sentry.init({
30
28
});
31
29
```
32
30
33
-
TwP mode can be disabled by configuring the SDK for [regular tracing](#enable-regular-tracing) or by entirely opting out of trace propagation ([completely disabling tracing](#completely-disable-tracing)).
31
+
TwP mode can be exited by configuring the SDK for [regular tracing](#enable-regular-tracing) or partially disabled by [opting out of trace propagation](#disable-trace-propagation).
34
32
35
33
<Alert>
36
34
@@ -58,9 +56,9 @@ Sentry.init({
58
56
59
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.
60
58
61
-
### Completely Disabling Tracing
59
+
### Disable Trace Propagation
62
60
63
-
To completely opt out of any distributed tracing capabilities, users can pass an empty array (or language-equivalent parameter) to the `tracePropagationTargets` option. This will prevent the SDK from propagating trace information any further.
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.
64
62
65
63
```js
66
64
Sentry.init({
@@ -78,10 +76,12 @@ Everything else (e.g. how to store the trace data and specific tracing options)
78
76
79
77
### Continuing Incoming Traces
80
78
81
-
SDKs in TwP mode must continue incoming traces (e.g. from incoming HTTP requests) and attach the trace data of that trace to any events that are created during the lifetime of this trace.
82
-
Furthermore, they must propagate the trace as usual to any outgoing requests.
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.
83
81
This means that continuing traces should work just like in the regular tracing mode (with spans).
84
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
85
### Starting a New Trace
86
86
87
87
If an SDK in TwP mode doesn't receive an incoming trace, it should start a new trace.
@@ -105,18 +105,18 @@ Furthermore, the [`trace` envelope header](/sdk/telemetry/traces/dynamic-samplin
105
105
106
106
Traces in TwP mode should have the same duration as regular traces.
107
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 (or current scope created within the isolation scope).
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
109
110
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
111
The exact storage mechanism is up to the SDK implementation, but we recommended using the same mechanism as for regular traces.
112
112
Usually this means storing the data on the scope in a field called `propagationContext` as [recommended here](/sdk/telemetry/traces/distributed-tracing/).
113
113
114
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 requiring a `spanId`—has an important implication on the Sentry product:
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
116
A non-existing `spanId` will be propagated along with the trace and attached to events.
117
117
While not ideal, we accept this limitation as the Sentry product can and should handle non-existing (parent) spans anyway.
118
118
119
-
As in regular tracing mode, for SDKs starting a new trace, the dynamic sampling context should be lazily populated and frozen for the duration of the trace.
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
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
121
122
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.
@@ -125,10 +125,11 @@ Note that in the case of using the non-recording span, the span is also not samp
125
125
126
126
## Historical Context
127
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, no trace data would be attached to any events.
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
+
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.
130
131
131
132
The name "Tracing without Performance" was chosen because at the time of introduction, we associated spans purely with performance monitoring.
132
133
Today, we associate spans with "Tracing" in general, and only (some of) the data from spans with Performance Monitoring.
133
134
This is why the name from today's perspective is a bit misleading.
134
-
As a mental model, think of TwP as "Tracing without Spans".
135
+
As a mental model, think of TwP as "Trace propagation and continuation without Spans".
0 commit comments