feat: Add Tracing without Performance documentation

Author: Lms24

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

@@ -0,0 +1,134 @@
+---
+title: Tracing Without Performance
+---
+
+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.
+Internally, we call this mode "Tracing without Performance" (or "TwP" in short).
+TwP mode ensures that error events and other signals are still connected via a trace, even if users chose not to send spans or performance data.
+
+## Outcome
+
+Tracing without Performance is the default fallback behavior of SDKs, when users [don't specify any tracing options](#configuration).
+
+This means that SDKs in this mode always:
+
+- continue incoming traces
+- attache `event.contexts.trace` context on events (e.g. errors, check-ins)
+- attach the `trace` envelope header to Sentry envelopes, populated from the dynamic sampling context
+- 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)
+
+If users [explicitly opt out](#completely-disable-tracing) of all tracing capabilities, TwP mode shall no longer be active.
+
+## Configuration
+
+Twp is active by default if users don't specify sampling options that enable span collection and sending.
+For example, the following trivial SDK setup (note the absence of sampling options) enables TwP:
+
+```JavaScript
+Sentry.init({
+  dsn: "___PUBLIC_DSN___",
+});
+```
+
+TwP mode can be disabled by either "upgrading" to Tracing _with_ Performance (see below) or by entirely opting out of trace propagation.
+
+<Alert>
+
+Note that some SDKs like the JavaScript Browser SDK require additional integrations to enable tracing all together.
+This is fine as long as there's a good reason why additional configuration is required (like keeping bundle size in check in JS).
+
+</Alert>
+
+### Upgrading to Tracing With Performance
+
+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).
+
+This can be achieve by specifying `tracesSampleRate` or `tracesSampler` or any other equivalent option in the SDK configuration:
+
+```js
+Sentry.init({
+  dsn: "___PUBLIC_DSN___",
+  tracesSampleRate: 0.1,
+  // or
+  tracesSampler: () => {
+    /*...*/
+  },
+});
+```
+
+Importantly, also setting `tracesSampleRate: 0` means that TwP mode is disabled.
+
+### Completely Disabling Tracing
+
+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.
+
+```js
+Sentry.init({
+  dsn: "___PUBLIC_DSN___",
+  tracePropagationTargets: [],
+});
+```
+
+Note that for incoming requests with trace headers, SDKs should still continue this trace but not propagate it further downstream.
+
+## Implementation
+
+SDKs implementing TwP mode must adhere to the behavior described in this section.
+Everything else (e.g. how to store the trace data and specific tracing options) is considered an implementation detail and is free to be implemented as needed.
+
+### Continuing incoming traces
+
+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.
+Furthermore, they must propagate the trace as usual to any outgoing requests.
+This means that continuing traces should work just like in the regular tracing mode (with spans).
+
+### Starting a new Trace
+
+If an SDK in TwP mode doesn't receive an incoming trace, it should start a new trace.
+In this case, the new trace is not sampled (as in, there is no sampling decision, neither positive nor negative).
+Instead, the sampling decision is _deferred_ to the next downstream SDK.
+
+This means that
+
+- the SDK must not include a sampled flag in the [`sentry-trace` header](../#header-sentry-trace), meaning the header has the format `<traceId>-<spanId>`.
+  More details on the [sampled flag](../#the-sampled-value).
+- the [dynamic sampling context](https://develop.sentry.dev/sdk/telemetry/traces/dynamic-sampling-context/), propagated via `baggage` must not contain the `sentry-sampled` key.
+
+### Attaching Trace Data to Events and Envelopes
+
+Any event created by an SDK in TwP mode must include the [`trace` context](/sdk/event-payloads/contexts/#trace-context).
+This context should contain the trace data of the current trace, if available, just like in regular tracing mode.
+
+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.
+
+### Trace Duration and Storage
+
+Traces in TwP mode should have the same duration as regular traces.
+For example, a TwP trace for a backend server should generally last for the duration of one individual request.
+This usually corresponds with the lifetime of an isolation scope (or current scope created within the isolation scope).
+
+SDKs in TwP mode must store trace data in a way that it can be attached to events and propagated to outgoing requests.
+The exact storage mechanism is up to the SDK implementation but it is recommended to use the same mechanism as for regular traces.
+Usually this means storing the data on the scope in a field called `propagationContext` as [recommended here](/sdk/telemetry/traces/distributed-tracing/).
+
+Related, the `propagationContext` should be populated with a random `traceId` and `spanId` if no incoming trace is present.
+This—in combination with the `sentry-trace` header specification requiring a `spanId`—has an important implication on the Sentry product:
+A non-existing `spanId` will be propagated along with the trace and attached to events.
+While not ideal, we accept this limitation as the Sentry product can and should handle non-existing (parent) spans anyway.
+
+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.
+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`).
+
+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.
+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.
+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).
+
+## Historical Context
+
+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 and otherwise not attach trace data to any events.
+The primary motivation for TwP was to ensure that errors across application or service boundaries are still connected if they occurred in the same trace.
+
+The name "Tracing without Performance" was chosen because at the time of introduction, we associated spans purely with performance monitoring.
+Today, we associate spans more towards "Tracing" in general, and only (some of) the data from spans with Performance Monitoring.
+This is why the name from today's perspective is a bit misleading.
+As a mental model, think of TwP as "Tracing without Spans".