Skip to content

Commit 8436336

Browse files
s1gr1ds1gr1d
authored
docs(js): Add docs for strictTraceContinuation and orgId (#14459)
## DESCRIBE YOUR PR Docs for `strictTraceContinuation` and `orgId` ([related PR](getsentry/sentry-javascript#16313)). I'm not 100% sure where I should put the `orgId` as it does not 100% fit into the "Tracing Options" section but it's currently only used for tracing. closes getsentry/sentry-javascript#16308 ## 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 --> - [ ] 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:* - [ ] 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)
1 parent 75ed094 commit 8436336

File tree

7 files changed

+236
-8
lines changed

7 files changed

+236
-8
lines changed

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

Lines changed: 30 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -18,6 +18,21 @@ sidebar_order: 1
1818

1919
</SdkOption>
2020

21+
<PlatformCategorySection supported={["server", "serverless"]}>
22+
<SdkOption name="orgId" type='`${number}` | number'>
23+
24+
The organization ID for your Sentry project.
25+
26+
The SDK will try to extract the organization ID from the DSN. If it cannot be found, or if you need to override it,
27+
you can provide the ID with this option. The organization ID is used for trace propagation and features like `strictTraceContinuation`.
28+
29+
<Alert level="info">
30+
The organization ID is used for features like <PlatformLink to="/configuration/options#strictTraceContinuation">strict trace continuation</PlatformLink>.
31+
</Alert>
32+
33+
</SdkOption>
34+
</PlatformCategorySection>
35+
2136
<SdkOption name="debug" type='boolean' defaultValue='false'>
2237

2338
Turns debug mode on or off. If debug is enabled SDK will attempt to print out useful debugging information about what the SDK is doing.
@@ -379,6 +394,21 @@ If you want to disable trace propagation, you can set this option to `[]`.
379394

380395
</SdkOption>
381396

397+
398+
<PlatformCategorySection supported={["server", "serverless"]}>
399+
<SdkOption name="strictTraceContinuation" type='boolean' defaultValue='false'>
400+
401+
If set to `true`, the SDK will only continue a trace if the organization ID of the incoming trace found in the
402+
`baggage` header matches the organization ID of the current Sentry client.
403+
404+
The client's organization ID is extracted from the DSN or can be set with the <PlatformLink to={'/configuration/options#orgId'}>`orgId` option</PlatformLink>.
405+
406+
If the organization IDs do not match, the SDK will start a new trace instead of continuing the incoming one.
407+
This is useful to prevent traces of unknown third-party services from being continued in your application.
408+
409+
</SdkOption>
410+
</PlatformCategorySection>
411+
382412
<PlatformCategorySection supported={['browser']}>
383413

384414
<SdkOption name="beforeSendTransaction" type='(event: TransactionEvent, hint: EventHint) => TransactionEvent | null'>

‎platform-includes/distributed-tracing/how-to-use/javascript.nextjs.mdx‎

Lines changed: 33 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -71,6 +71,39 @@ This configuration lets your app track user actions across:
7171

7272
If your app crashes while a user is uploading a photo, you can trace exactly where the problem occurred - in the app itself, the main API, or the media service.
7373

74+
### Strict Trace Continuation
75+
76+
_Available since SDK version 10_
77+
78+
When your application receives requests, they might include `sentry-trace` and `baggage` headers from an upstream service that is also using Sentry.
79+
By default, the SDK will continue the trace from these incoming headers. However, this behavior can be undesirable if the requests are from a third-party service,
80+
as it can lead to unwanted traces, increased billing, and skewed performance data.
81+
82+
To prevent this, you can enable `strictTraceContinuation`. When this option is set to `true`, the SDK checks the incoming request for Sentry trace information and only continues the trace if it belongs to the same Sentry organization.
83+
Otherwise, it starts a new trace.
84+
This is useful if your application is a public API or receives requests from services outside your organization.
85+
86+
```javascript {5}
87+
Sentry.init({
88+
dsn: "___PUBLIC_DSN___",
89+
tracesSampleRate: 1.0,
90+
// Ensure that only traces from your own organization are continued
91+
strictTraceContinuation: true,
92+
});
93+
```
94+
95+
The SDK automatically parses the organization ID from your DSN. If you use a DSN format that doesn't include the organization ID (number followed by the letter `"o"`), or if you need to override it, you can provide it manually using the `orgId` option:
96+
97+
```javascript {6}
98+
Sentry.init({
99+
dsn: "___PUBLIC_DSN___",
100+
tracesSampleRate: 1.0,
101+
strictTraceContinuation: true,
102+
// Manually provide your organization ID (overrides organization ID parsed from DSN)
103+
orgId: 12345,
104+
});
105+
```
106+
74107
### Disabling Distributed Tracing
75108

76109
If you want to disable distributed tracing and ensure no Sentry trace headers are sent, you can configure your SDK like this:

‎platform-includes/distributed-tracing/how-to-use/javascript.node.mdx‎

Lines changed: 34 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -10,7 +10,7 @@ Sentry.init({
1010

1111
<Alert>
1212

13-
Note: port numbers are relevant for trace propagation and the origin. You may need to configure the `tracePropagationTargets` to ensure that traces are propagated across your services if they run on different ports.
13+
Note: port numbers are relevant for trace propagation and the origin. You may need to configure the `tracePropagationTargets` to ensure that traces are propagated across your services if they run on different ports.
1414

1515
For example, if you have a Node.js backend running locally on port 3000, that destination (`http://localhost:3000`) should be added to the `tracePropagationTargets` array on your frontend to ensure that CORS doesn't restrict the propagation of traces.
1616

@@ -62,6 +62,39 @@ This configuration lets your app track user actions across:
6262

6363
If your app crashes while a user is uploading a photo, you can trace exactly where the problem occurred - in the app itself, the main API, or the media service.
6464

65+
### Strict Trace Continuation
66+
67+
_Available since SDK version 10_
68+
69+
When your application receives requests, they might include `sentry-trace` and `baggage` headers from an upstream service that is also using Sentry.
70+
By default, the SDK will continue the trace from these incoming headers. However, this behavior can be undesirable if the requests are from a third-party service,
71+
as it can lead to unwanted traces, increased billing, and skewed performance data.
72+
73+
To prevent this, you can enable `strictTraceContinuation`. When this option is set to `true`, the SDK checks the incoming request for Sentry trace information and only continues the trace if it belongs to the same Sentry organization.
74+
Otherwise, it starts a new trace.
75+
This is useful if your application is a public API or receives requests from services outside your organization.
76+
77+
```javascript {5}
78+
Sentry.init({
79+
dsn: "___PUBLIC_DSN___",
80+
tracesSampleRate: 1.0,
81+
// Ensure that only traces from your own organization are continued
82+
strictTraceContinuation: true,
83+
});
84+
```
85+
86+
The SDK automatically parses the organization ID from your DSN. If you use a DSN format that doesn't include the organization ID (number followed by the letter `"o"`), or if you need to override it, you can provide it manually using the `orgId` option:
87+
88+
```javascript {6}
89+
Sentry.init({
90+
dsn: "___PUBLIC_DSN___",
91+
tracesSampleRate: 1.0,
92+
strictTraceContinuation: true,
93+
// Manually provide your organization ID (overrides organization ID parsed from DSN)
94+
orgId: 12345,
95+
});
96+
```
97+
6598
### Disabling Distributed Tracing
6699

67100
If you want to disable distributed tracing and ensure no Sentry trace headers are sent, you can configure your SDK like this:

‎platform-includes/distributed-tracing/how-to-use/javascript.nuxt.mdx‎

Lines changed: 36 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -1,10 +1,10 @@
1-
If you're using the current version of our Nuxt SDK, distributed tracing will work out of the box for the client and server runtimes.
1+
If you're using the current version of our Nuxt SDK, distributed tracing will work out of the box for the client and server runtimes.
22

33
To get around possible [Browser CORS](https://developer.mozilla.org/en-US/docs/Web/HTTP/CORS) issues, you should define `tracePropagationTargets` for client-side.
44

55
<Alert>
66

7-
Note: port numbers are relevant for trace propagation and the origin. You may need to configure the `tracePropagationTargets` to ensure that traces are propagated across your services if they run on different ports.
7+
Note: port numbers are relevant for trace propagation and the origin. You may need to configure the `tracePropagationTargets` to ensure that traces are propagated across your services if they run on different ports.
88

99
For example, if you have a Node.js backend running locally on port 3000, that destination (`http://localhost:3000`) should be added to the `tracePropagationTargets` array on your frontend to ensure that CORS doesn't restrict the propagation of traces.
1010

@@ -59,4 +59,37 @@ This configuration lets your app track user actions across:
5959
* Your media server (handles images, videos, etc.)
6060
* Any local API endpoints in your app
6161

62-
If your app crashes while a user is uploading a photo, you can trace exactly where the problem occurred - in the app itself, the main API, or the media service.
62+
If your app crashes while a user is uploading a photo, you can trace exactly where the problem occurred - in the app itself, the main API, or the media service.
63+
64+
### Strict Trace Continuation
65+
66+
_Available since SDK version 10_
67+
68+
When your application receives requests, they might include `sentry-trace` and `baggage` headers from an upstream service that is also using Sentry.
69+
By default, the SDK will continue the trace from these incoming headers. However, this behavior can be undesirable if the requests are from a third-party service,
70+
as it can lead to unwanted traces, increased billing, and skewed performance data.
71+
72+
To prevent this, you can enable `strictTraceContinuation`. When this option is set to `true`, the SDK checks the incoming request for Sentry trace information and only continues the trace if it belongs to the same Sentry organization.
73+
Otherwise, it starts a new trace.
74+
This is useful if your application is a public API or receives requests from services outside your organization.
75+
76+
```javascript {5}
77+
Sentry.init({
78+
dsn: "___PUBLIC_DSN___",
79+
tracesSampleRate: 1.0,
80+
// Ensure that only traces from your own organization are continued
81+
strictTraceContinuation: true,
82+
});
83+
```
84+
85+
The SDK automatically parses the organization ID from your DSN. If you use a DSN format that doesn't include the organization ID (number followed by the letter `"o"`), or if you need to override it, you can provide it manually using the `orgId` option:
86+
87+
```javascript {6}
88+
Sentry.init({
89+
dsn: "___PUBLIC_DSN___",
90+
tracesSampleRate: 1.0,
91+
strictTraceContinuation: true,
92+
// Manually provide your organization ID (overrides organization ID parsed from DSN)
93+
orgId: 12345,
94+
});
95+
```

‎platform-includes/distributed-tracing/how-to-use/javascript.remix.mdx‎

Lines changed: 34 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -35,7 +35,7 @@ To get around possible [Browser CORS](https://developer.mozilla.org/en-US/docs/W
3535

3636
<Alert>
3737

38-
Note: port numbers are relevant for trace propagation and the origin. You may need to configure the `tracePropagationTargets` to ensure that traces are propagated across your services if they run on different ports.
38+
Note: port numbers are relevant for trace propagation and the origin. You may need to configure the `tracePropagationTargets` to ensure that traces are propagated across your services if they run on different ports.
3939

4040
For example, if you have a Node.js backend running locally on port 3000, that destination (`http://localhost:3000`) should be added to the `tracePropagationTargets` array on your frontend to ensure that CORS doesn't restrict the propagation of traces.
4141

@@ -100,6 +100,39 @@ This configuration lets your app track user actions across:
100100

101101
If your app crashes while a user is uploading a photo, you can trace exactly where the problem occurred - in the app itself, the main API, or the media service.
102102

103+
### Strict Trace Continuation
104+
105+
_Available since SDK version 10_
106+
107+
When your application receives requests, they might include `sentry-trace` and `baggage` headers from an upstream service that is also using Sentry.
108+
By default, the SDK will continue the trace from these incoming headers. However, this behavior can be undesirable if the requests are from a third-party service,
109+
as it can lead to unwanted traces, increased billing, and skewed performance data.
110+
111+
To prevent this, you can enable `strictTraceContinuation`. When this option is set to `true`, the SDK checks the incoming request for Sentry trace information and only continues the trace if it belongs to the same Sentry organization.
112+
Otherwise, it starts a new trace.
113+
This is useful if your application is a public API or receives requests from services outside your organization.
114+
115+
```javascript {5}
116+
Sentry.init({
117+
dsn: "___PUBLIC_DSN___",
118+
tracesSampleRate: 1.0,
119+
// Ensure that only traces from your own organization are continued
120+
strictTraceContinuation: true,
121+
});
122+
```
123+
124+
The SDK automatically parses the organization ID from your DSN. If you use a DSN format that doesn't include the organization ID (number followed by the letter `"o"`), or if you need to override it, you can provide it manually using the `orgId` option:
125+
126+
```javascript {6}
127+
Sentry.init({
128+
dsn: "___PUBLIC_DSN___",
129+
tracesSampleRate: 1.0,
130+
strictTraceContinuation: true,
131+
// Manually provide your organization ID (overrides organization ID parsed from DSN)
132+
orgId: 12345,
133+
});
134+
```
135+
103136
### Disabling Distributed Tracing
104137

105138
If you want to disable distributed tracing and ensure no Sentry trace headers are sent, you can configure your SDK like this:

‎platform-includes/distributed-tracing/how-to-use/javascript.solidstart.mdx‎

Lines changed: 34 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -29,7 +29,7 @@ To get around possible [Browser CORS](https://developer.mozilla.org/en-US/docs/W
2929

3030
<Alert>
3131

32-
Note: port numbers are relevant for trace propagation and the origin. You may need to configure the `tracePropagationTargets` to ensure that traces are propagated across your services if they run on different ports.
32+
Note: port numbers are relevant for trace propagation and the origin. You may need to configure the `tracePropagationTargets` to ensure that traces are propagated across your services if they run on different ports.
3333

3434
For example, if you have a Node.js backend running locally on port 3000, that destination (`http://localhost:3000`) should be added to the `tracePropagationTargets` array on your frontend to ensure that CORS doesn't restrict the propagation of traces.
3535

@@ -93,3 +93,36 @@ This configuration lets your app track user actions across:
9393
* Any local API endpoints in your app
9494

9595
If your app crashes while a user is uploading a photo, you can trace exactly where the problem occurred - in the app itself, the main API, or the media service.
96+
97+
### Strict Trace Continuation
98+
99+
_Available since SDK version 10_
100+
101+
When your application receives requests, they might include `sentry-trace` and `baggage` headers from an upstream service that is also using Sentry.
102+
By default, the SDK will continue the trace from these incoming headers. However, this behavior can be undesirable if the requests are from a third-party service,
103+
as it can lead to unwanted traces, increased billing, and skewed performance data.
104+
105+
To prevent this, you can enable `strictTraceContinuation`. When this option is set to `true`, the SDK checks the incoming request for Sentry trace information and only continues the trace if it belongs to the same Sentry organization.
106+
Otherwise, it starts a new trace.
107+
This is useful if your application is a public API or receives requests from services outside your organization.
108+
109+
```javascript {5}
110+
Sentry.init({
111+
dsn: "___PUBLIC_DSN___",
112+
tracesSampleRate: 1.0,
113+
// Ensure that only traces from your own organization are continued
114+
strictTraceContinuation: true,
115+
});
116+
```
117+
118+
The SDK automatically parses the organization ID from your DSN. If you use a DSN format that doesn't include the organization ID (number followed by the letter `"o"`), or if you need to override it, you can provide it manually using the `orgId` option:
119+
120+
```javascript {6}
121+
Sentry.init({
122+
dsn: "___PUBLIC_DSN___",
123+
tracesSampleRate: 1.0,
124+
strictTraceContinuation: true,
125+
// Manually provide your organization ID (overrides organization ID parsed from DSN)
126+
orgId: 12345,
127+
});
128+
```

‎platform-includes/distributed-tracing/how-to-use/javascript.sveltekit.mdx‎

Lines changed: 35 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -1,10 +1,10 @@
1-
If you're using the current version of our SvelteKit SDK, distributed tracing will work out of the box for the client and server runtimes.
1+
If you're using the current version of our SvelteKit SDK, distributed tracing will work out of the box for the client and server runtimes.
22

33
When you are interacting with other external API systems, you might have to define `tracePropagationTargets` to get around possible [Browser CORS](https://developer.mozilla.org/en-US/docs/Web/HTTP/CORS) issues.
44

55
<Alert>
66

7-
Note: port numbers are relevant for trace propagation and the origin. You may need to configure the `tracePropagationTargets` to ensure that traces are propagated across your services if they run on different ports.
7+
Note: port numbers are relevant for trace propagation and the origin. You may need to configure the `tracePropagationTargets` to ensure that traces are propagated across your services if they run on different ports.
88

99
For example, if you have a Node.js backend running locally on port 3000, that destination (`http://localhost:3000`) should be added to the `tracePropagationTargets` array on your frontend to ensure that CORS doesn't restrict the propagation of traces.
1010

@@ -71,6 +71,39 @@ This configuration lets your app track user actions across:
7171

7272
If your app crashes while a user is uploading a photo, you can trace exactly where the problem occurred - in the app itself, the main API, or the media service.
7373

74+
### Strict Trace Continuation
75+
76+
_Available since SDK version 10_
77+
78+
When your application receives requests, they might include `sentry-trace` and `baggage` headers from an upstream service that is also using Sentry.
79+
By default, the SDK will continue the trace from these incoming headers. However, this behavior can be undesirable if the requests are from a third-party service,
80+
as it can lead to unwanted traces, increased billing, and skewed performance data.
81+
82+
To prevent this, you can enable `strictTraceContinuation`. When this option is set to `true`, the SDK checks the incoming request for Sentry trace information and only continues the trace if it belongs to the same Sentry organization.
83+
Otherwise, it starts a new trace.
84+
This is useful if your application is a public API or receives requests from services outside your organization.
85+
86+
```javascript {5}
87+
Sentry.init({
88+
dsn: "___PUBLIC_DSN___",
89+
tracesSampleRate: 1.0,
90+
// Ensure that only traces from your own organization are continued
91+
strictTraceContinuation: true,
92+
});
93+
```
94+
95+
The SDK automatically parses the organization ID from your DSN. If you use a DSN format that doesn't include the organization ID (number followed by the letter `"o"`), or if you need to override it, you can provide it manually using the `orgId` option:
96+
97+
```javascript {6}
98+
Sentry.init({
99+
dsn: "___PUBLIC_DSN___",
100+
tracesSampleRate: 1.0,
101+
strictTraceContinuation: true,
102+
// Manually provide your organization ID (overrides organization ID parsed from DSN)
103+
orgId: 12345,
104+
});
105+
```
106+
74107
### Disabling Distributed Tracing
75108

76109
If you want to disable distributed tracing and ensure no Sentry trace headers are sent, you can configure your SDK like this:

0 commit comments

Comments
 (0)