docs(sdk): restore span-trace-propagation.mdx

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"):
+    ...
+```