From 7de3e73758ea7caf8316f1b8b139522204fe6278 Mon Sep 17 00:00:00 2001
From: Stephanie Anderson <stephanie.anderson@sentry.io>
Date: Wed, 25 Feb 2026 14:24:39 +0100
Subject: [PATCH] docs(sdk): restore span-trace-propagation.mdx

This file was accidentally deleted in the trace propagation extraction.
It should remain as a standalone spec page until its content is fully
covered by the new trace-propagation spec.

Co-Authored-By: Claude <noreply@anthropic.com>
---
 .../spans/span-trace-propagation.mdx          | 77 +++++++++++++++++++
 1 file changed, 77 insertions(+)
 create mode 100644 develop-docs/sdk/telemetry/spans/span-trace-propagation.mdx

diff --git a/develop-docs/sdk/telemetry/spans/span-trace-propagation.mdx b/develop-docs/sdk/telemetry/spans/span-trace-propagation.mdx
new file mode 100644
index 0000000000000..82664b003bf91
--- /dev/null
+++ b/develop-docs/sdk/telemetry/spans/span-trace-propagation.mdx
@@ -0,0 +1,77 @@
+---
+title: Span Trace Propagation
+---
+
+<Alert level="warning">
+  🚧 This document is work in progress.
+</Alert>
+
+<Alert level="info">
+  This document uses key words such as "MUST", "SHOULD", and "MAY" as defined in [RFC 2119](https://www.ietf.org/rfc/rfc2119.txt) to indicate requirement levels.
+</Alert>
+
+## Continue an incoming trace
+
+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.
+
+```js
+Sentry.continueTrace({
+  sentryTrace: request.headers['sentry-trace'],
+  baggage: request.headers['baggage'],
+}, () => {
+  Sentry.startSpan({ name: 'test' }, () => {
+    // ....
+  });
+})
+```
+
+```python
+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.
+
+## Continue an outgoing trace
+
+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.
+
+```js
+const traceData = Sentry.getTraceData()
+```
+
+```python
+traceparent = sentry_sdk.get_traceparent()
+baggage = sentry_sdk.get_baggage()
+```
+
+## Starting a new trace
+
+The SDK MUST offer a method to clear trace propagation data, allowing to create spans with a fresh new trace.
+
+```js
+Sentry.startNewTrace(() => {
+  Sentry.startSpan({ name: 'segment under trace 1' }, () => {...});
+})
+
+Sentry.startNewTrace(() => {
+  Sentry.startSpan({ name: 'segment under trace 2' }, () => {...});
+})
+```
+
+```python
+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"):
+    ...
+```