Skip to content

Commit b12363a

Browse files
authored
feat(js): Add propagateTraceparent option documentation (#14805)
<!-- Use this checklist to make sure your PR is ready for merge. You may delete any sections you don't need. --> ## DESCRIBE YOUR PR To be merged after getsentry/sentry-javascript#17509 was released This PR adds documentation for the new, browser-SDK-only, `propagateTraceparent` option (see [develop docs](https://develop.sentry.dev/sdk/telemetry/traces/#propagatetraceparent)). It also adjusts our "Dealing with CORS Issues" page to include `traceparent` in the `CORS` configuration if users opted into the option. ## IS YOUR CHANGE URGENT? Help us prioritize incoming PRs by letting us know when the change needs to go live. - [ ] Urgent deadline (GA date, etc.): <!-- ENTER DATE HERE --> - [ ] Other deadline: <!-- ENTER DATE HERE --> - [x] None: Not urgent, can wait up to 1 week+ ## SLA - Teamwork makes the dream work, so please add a reviewer to your PRs. - Please give the docs team up to 1 week to review your PR unless you've added an urgent due date to it. Thanks in advance for your help! ## PRE-MERGE CHECKLIST *Make sure you've checked the following before merging your changes:* - [x] Checked Vercel preview for correctness, including links - [ ] PR was reviewed and approved by any necessary SMEs (subject matter experts) - [ ] PR was reviewed and approved by a member of the [Sentry docs team](https://github.com/orgs/getsentry/teams/docs) ## LEGAL BOILERPLATE <!-- Sentry employees and contractors can delete or ignore this section. --> Look, I get it. The entity doing business as "Sentry" was incorporated in the State of Delaware in 2015 as Functional Software, Inc. and is gonna need some rights from me in order to utilize my contributions in this here PR. So here's the deal: I retain all rights, title and interest in and to my contributions, and by keeping this boilerplate intact I confirm that Sentry can use, modify, copy, and redistribute my contributions, under Sentry's choice of terms. ## EXTRA RESOURCES - [Sentry Docs contributor guide](https://docs.sentry.io/contributing/)
1 parent 91811b6 commit b12363a

File tree

2 files changed

+30
-1
lines changed
  • docs/platforms/javascript/common

2 files changed

+30
-1
lines changed

docs/platforms/javascript/common/configuration/options.mdx

Lines changed: 21 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -443,6 +443,27 @@ By default, no spans are ignored.
443443

444444
</SdkOption>
445445

446+
<PlatformCategorySection supported={['browser']}>
447+
448+
<SdkOption name="propagateTraceparent" type='boolean' defaultValue='false'>
449+
450+
_Available since: `10.10.0`_
451+
452+
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`.
453+
This header is attached in addition to the `sentry-trace` and `baggage` headers.
454+
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.
455+
456+
**Important:** Make sure that your backend services' CORS configuration allows the `traceparent` header.
457+
Otherwise, requests might be blocked.
458+
Use the [`tracePropagationTargets` option](#tracepropagationtargets) to control which requests the `traceparent` header is attached to.
459+
See <PlatformLink to="/tracing/distributed-tracing/dealing-with-cors-issues/">Dealing with CORS Issues</PlatformLink> for more information.
460+
461+
Note that this option is only available for browser SDKs.
462+
463+
</SdkOption>
464+
465+
</PlatformCategorySection>
466+
446467
## Session Replay Options
447468

448469
<SdkOption name="replaysSessionSampleRate" type='number' categorySupported={['browser']}>

docs/platforms/javascript/common/tracing/distributed-tracing/dealing-with-cors-issues/index.mdx

Lines changed: 9 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -20,7 +20,7 @@ If your frontend and backend are hosted on different domains (for example, your
2020

2121
## Understanding Trace Propagation
2222

23-
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.
23+
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.
2424

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

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

58+
### W3C traceparent header
59+
60+
If you set <PlatformLink to="/configuration/options#propagateTraceparent">`propagateTraceparent` option</PlatformLink> to `true`, you also need to allow the `traceparent` header:
61+
62+
```
63+
Access-Control-Allow-Headers: sentry-trace, baggage, traceparent
64+
```
65+
5866
## Disabling Trace Propagation
5967

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

0 commit comments

Comments
 (0)