Skip to content

Commit ef13f78

Browse files
committed
apply code review suggestions, add more links
1 parent d018084 commit ef13f78

File tree

1 file changed

+20
-19
lines changed

1 file changed

+20
-19
lines changed

develop-docs/sdk/telemetry/traces/tracing-without-performance.mdx

Lines changed: 20 additions & 19 deletions
Original file line numberDiff line numberDiff line change
@@ -2,26 +2,24 @@
22
title: Tracing Without Performance
33
---
44

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)).
77
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.
88

9-
## Outcome
9+
## Behavior
1010

1111
Tracing without Performance is the default fallback behavior of SDKs, when users [don't specify any tracing options](#configuration).
1212

13-
This means that SDKs in this mode always:
13+
This means that SDKs by default always:
1414

1515
- 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)
1717
- 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)
2119

2220
## Configuration
2321

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)).
2523
For example, the following trivial SDK setup (note the absence of sampling options) enables TwP:
2624

2725
```JavaScript
@@ -30,7 +28,7 @@ Sentry.init({
3028
});
3129
```
3230

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).
3432

3533
<Alert>
3634

@@ -58,9 +56,9 @@ Sentry.init({
5856

5957
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.
6058

61-
### Completely Disabling Tracing
59+
### Disable Trace Propagation
6260

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.
6462

6563
```js
6664
Sentry.init({
@@ -78,10 +76,12 @@ Everything else (e.g. how to store the trace data and specific tracing options)
7876

7977
### Continuing Incoming Traces
8078

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.
8381
This means that continuing traces should work just like in the regular tracing mode (with spans).
8482

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+
8585
### Starting a New Trace
8686

8787
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
105105

106106
Traces in TwP mode should have the same duration as regular traces.
107107
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).
109109

110110
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.
111111
The exact storage mechanism is up to the SDK implementation, but we recommended using the same mechanism as for regular traces.
112112
Usually this means storing the data on the scope in a field called `propagationContext` as [recommended here](/sdk/telemetry/traces/distributed-tracing/).
113113

114114
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:
116116
A non-existing `spanId` will be propagated along with the trace and attached to events.
117117
While not ideal, we accept this limitation as the Sentry product can and should handle non-existing (parent) spans anyway.
118118

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.
120120
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`).
121121

122122
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
125125

126126
## Historical Context
127127

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+
129130
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.
130131

131132
The name "Tracing without Performance" was chosen because at the time of introduction, we associated spans purely with performance monitoring.
132133
Today, we associate spans with "Tracing" in general, and only (some of) the data from spans with Performance Monitoring.
133134
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

Comments
 (0)