Skip to content

feat(js): Add propagateTraceparent option documentation #14805

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 1 commit into from
Sep 9, 2025
Merged

feat(js): Add propagateTraceparent option documentation #14805

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
21 changes: 21 additions & 0 deletions docs/platforms/javascript/common/configuration/options.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -443,6 +443,27 @@ By default, no spans are ignored.

</SdkOption>

<PlatformCategorySection supported={['browser']}>

<SdkOption name="propagateTraceparent" type='boolean' defaultValue='false'>

_Available since: `10.10.0`_

If set to `true`, the SDK adds the [W3C `traceparent` header](https://www.w3.org/TR/trace-context/) to outgoing Http requests made via `fetch` or `XMLHttpRequest`.
This header is attached in addition to the `sentry-trace` and `baggage` headers.
Set this option to `true` if your backend services are instrumented with e.g. OpenTelemetry or other W3C Trace Context compatible libraries and you want to continue traces from the client.

**Important:** Make sure that your backend services' CORS configuration allows the `traceparent` header.
Otherwise, requests might be blocked.
Use the [`tracePropagationTargets` option](#tracepropagationtargets) to control which requests the `traceparent` header is attached to.
See <PlatformLink to="/tracing/distributed-tracing/dealing-with-cors-issues/">Dealing with CORS Issues</PlatformLink> for more information.

Note that this option is only available for browser SDKs.

</SdkOption>

</PlatformCategorySection>

## Session Replay Options

<SdkOption name="replaysSessionSampleRate" type='number' categorySupported={['browser']}>
Expand Down
10 changes: 9 additions & 1 deletion ...avascript/common/tracing/distributed-tracing/dealing-with-cors-issues/index.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -20,7 +20,7 @@ If your frontend and backend are hosted on different domains (for example, your

## Understanding Trace Propagation

Sentry doesn't attach the `sentry-trace` and `baggage` headers to every outgoing request. Instead, it only attaches these headers to requests whose URLs match the patterns specified in the `tracePropagationTargets` configuration option.
Sentry doesn't attach the `sentry-trace` and `baggage` (and optionally `traceparent`) headers to every outgoing request. Instead, it only attaches these headers to requests whose URLs match the patterns specified in the `tracePropagationTargets` configuration option.

By default, `tracePropagationTargets` is set to `['localhost', /^\//]`, which means trace headers are only attached to:
- Requests containing `localhost` in their URL (e.g., `http://localhost:3000/api`)
Expand Down Expand Up @@ -55,6 +55,14 @@ Access-Control-Allow-Headers: sentry-trace, baggage

Your server's exact configuration will depend on your setup, but the important part is allowing both the `sentry-trace` and `baggage` headers.

### W3C traceparent header

If you set <PlatformLink to="/configuration/options#propagateTraceparent">`propagateTraceparent` option</PlatformLink> to `true`, you also need to allow the `traceparent` header:

```
Access-Control-Allow-Headers: sentry-trace, baggage, traceparent
```

## Disabling Trace Propagation

If you want to disable distributed tracing entirely and ensure no trace headers are sent:
Expand Down
Loading