Skip to content

Commit 78c211a

Browse files
s1gr1ds1gr1d
committed
docs(js): Add docs for strictTraceContinuation and orgId 
1 parent 01dc710 commit 78c211a

File tree

7 files changed

+219
-8
lines changed

7 files changed

+219
-8
lines changed

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

Lines changed: 25 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -379,6 +379,31 @@ If you want to disable trace propagation, you can set this option to `[]`.
379379

380380
</SdkOption>
381381

382+
383+
<PlatformCategorySection supported={["server", "serverless"]}>
384+
<SdkOption name="strictTraceContinuation" type='boolean' defaultValue='false'>
385+
386+
If set to `true`, the SDK will only continue a trace if the organization ID of the incoming trace found in the
387+
`baggage` header matches the organization ID of the current Sentry client.
388+
389+
The client's organization ID is extracted from the DSN or can be set with the `orgId` option.
390+
391+
If the organization IDs do not match, the SDK will start a new trace instead of continuing the incoming one.
392+
This is useful to prevent traces of unknown third-party services from being continued in your application.
393+
394+
</SdkOption>
395+
396+
<SdkOption name="orgId" type='`${number}` | number'>
397+
398+
The organization ID for your Sentry project.
399+
400+
The SDK will try to extract the organization ID from the DSN. If it cannot be found, or if you need to override it,
401+
you can provide the ID with this option. The organization ID is used for trace propagation and for features like `strictTraceContinuation`.
402+
403+
</SdkOption>
404+
405+
</PlatformCategorySection>
406+
382407
<PlatformCategorySection supported={['browser']}>
383408

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

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

Lines changed: 31 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -71,6 +71,37 @@ 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+
When your application receives requests, they might include `sentry-trace` and `baggage` headers from an upstream service that is also using Sentry.
77+
By default, the SDK will continue the trace from the incoming headers. This can be undesirable if the requests are from a third-party service,
78+
as it can lead to unwanted traces, increased billing, and skewed performance data.
79+
80+
To prevent this, you can enable `strictTraceContinuation`. When this option is set to `true`, the SDK checks the incoming request for Sentry trace information.
81+
It only continues the trace if it belongs to the same Sentry organization. Otherwise, it starts a new trace.
82+
This is useful if your application is a public API or receives requests from services outside your organization.
83+
84+
```javascript {5}
85+
Sentry.init({
86+
dsn: "___PUBLIC_DSN___",
87+
tracesSampleRate: 1.0,
88+
// Ensure that only traces from your own organization are continued
89+
strictTraceContinuation: true,
90+
});
91+
```
92+
93+
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:
94+
95+
```javascript {6}
96+
Sentry.init({
97+
dsn: "___PUBLIC_DSN___",
98+
tracesSampleRate: 1.0,
99+
strictTraceContinuation: true,
100+
// Manually provide your organization ID (overrides organization ID parsed from DSN)
101+
orgId: 12345,
102+
});
103+
```
104+
74105
### Disabling Distributed Tracing
75106

76107
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: 32 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,37 @@ 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+
When your application receives requests, they might include `sentry-trace` and `baggage` headers from an upstream service that is also using Sentry.
68+
By default, the SDK will continue the trace from the incoming headers. This can be undesirable if the requests are from a third-party service,
69+
as it can lead to unwanted traces, increased billing, and skewed performance data.
70+
71+
To prevent this, you can enable `strictTraceContinuation`. When this option is set to `true`, the SDK checks the incoming request for Sentry trace information.
72+
It only continues the trace if it belongs to the same Sentry organization. Otherwise, it starts a new trace.
73+
This is useful if your application is a public API or receives requests from services outside your organization.
74+
75+
```javascript {5}
76+
Sentry.init({
77+
dsn: "___PUBLIC_DSN___",
78+
tracesSampleRate: 1.0,
79+
// Ensure that only traces from your own organization are continued
80+
strictTraceContinuation: true,
81+
});
82+
```
83+
84+
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:
85+
86+
```javascript {6}
87+
Sentry.init({
88+
dsn: "___PUBLIC_DSN___",
89+
tracesSampleRate: 1.0,
90+
strictTraceContinuation: true,
91+
// Manually provide your organization ID (overrides organization ID parsed from DSN)
92+
orgId: 12345,
93+
});
94+
```
95+
6596
### Disabling Distributed Tracing
6697

6798
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: 34 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,35 @@ 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+
When your application receives requests, they might include `sentry-trace` and `baggage` headers from an upstream service that is also using Sentry.
67+
By default, the SDK will continue the trace from the incoming headers. This can be undesirable if the requests are from a third-party service,
68+
as it can lead to unwanted traces, increased billing, and skewed performance data.
69+
70+
To prevent this, you can enable `strictTraceContinuation`. When this option is set to `true`, the SDK checks the incoming request for Sentry trace information.
71+
It only continues the trace if it belongs to the same Sentry organization. Otherwise, it starts a new trace.
72+
This is useful if your application is a public API or receives requests from services outside your organization.
73+
74+
```javascript {5}
75+
Sentry.init({
76+
dsn: "___PUBLIC_DSN___",
77+
tracesSampleRate: 1.0,
78+
// Ensure that only traces from your own organization are continued
79+
strictTraceContinuation: true,
80+
});
81+
```
82+
83+
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:
84+
85+
```javascript {6}
86+
Sentry.init({
87+
dsn: "___PUBLIC_DSN___",
88+
tracesSampleRate: 1.0,
89+
strictTraceContinuation: true,
90+
// Manually provide your organization ID (overrides organization ID parsed from DSN)
91+
orgId: 12345,
92+
});
93+
```

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

Lines changed: 32 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,37 @@ 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+
When your application receives requests, they might include `sentry-trace` and `baggage` headers from an upstream service that is also using Sentry.
106+
By default, the SDK will continue the trace from the incoming headers. This can be undesirable if the requests are from a third-party service,
107+
as it can lead to unwanted traces, increased billing, and skewed performance data.
108+
109+
To prevent this, you can enable `strictTraceContinuation`. When this option is set to `true`, the SDK checks the incoming request for Sentry trace information.
110+
It only continues the trace if it belongs to the same Sentry organization. Otherwise, it starts a new trace.
111+
This is useful if your application is a public API or receives requests from services outside your organization.
112+
113+
```javascript {5}
114+
Sentry.init({
115+
dsn: "___PUBLIC_DSN___",
116+
tracesSampleRate: 1.0,
117+
// Ensure that only traces from your own organization are continued
118+
strictTraceContinuation: true,
119+
});
120+
```
121+
122+
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:
123+
124+
```javascript {6}
125+
Sentry.init({
126+
dsn: "___PUBLIC_DSN___",
127+
tracesSampleRate: 1.0,
128+
strictTraceContinuation: true,
129+
// Manually provide your organization ID (overrides organization ID parsed from DSN)
130+
orgId: 12345,
131+
});
132+
```
133+
103134
### Disabling Distributed Tracing
104135

105136
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: 32 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,34 @@ 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+
When your application receives requests, they might include `sentry-trace` and `baggage` headers from an upstream service that is also using Sentry.
100+
By default, the SDK will continue the trace from the incoming headers. This can be undesirable if the requests are from a third-party service,
101+
as it can lead to unwanted traces, increased billing, and skewed performance data.
102+
103+
To prevent this, you can enable `strictTraceContinuation`. When this option is set to `true`, the SDK checks the incoming request for Sentry trace information.
104+
It only continues the trace if it belongs to the same Sentry organization. Otherwise, it starts a new trace.
105+
This is useful if your application is a public API or receives requests from services outside your organization.
106+
107+
```javascript {5}
108+
Sentry.init({
109+
dsn: "___PUBLIC_DSN___",
110+
tracesSampleRate: 1.0,
111+
// Ensure that only traces from your own organization are continued
112+
strictTraceContinuation: true,
113+
});
114+
```
115+
116+
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:
117+
118+
```javascript {6}
119+
Sentry.init({
120+
dsn: "___PUBLIC_DSN___",
121+
tracesSampleRate: 1.0,
122+
strictTraceContinuation: true,
123+
// Manually provide your organization ID (overrides organization ID parsed from DSN)
124+
orgId: 12345,
125+
});
126+
```

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

Lines changed: 33 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,37 @@ 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+
When your application receives requests, they might include `sentry-trace` and `baggage` headers from an upstream service that is also using Sentry.
77+
By default, the SDK will continue the trace from the incoming headers. This can be undesirable if the requests are from a third-party service,
78+
as it can lead to unwanted traces, increased billing, and skewed performance data.
79+
80+
To prevent this, you can enable `strictTraceContinuation`. When this option is set to `true`, the SDK checks the incoming request for Sentry trace information.
81+
It only continues the trace if it belongs to the same Sentry organization. Otherwise, it starts a new trace.
82+
This is useful if your application is a public API or receives requests from services outside your organization.
83+
84+
```javascript {5}
85+
Sentry.init({
86+
dsn: "___PUBLIC_DSN___",
87+
tracesSampleRate: 1.0,
88+
// Ensure that only traces from your own organization are continued
89+
strictTraceContinuation: true,
90+
});
91+
```
92+
93+
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:
94+
95+
```javascript {6}
96+
Sentry.init({
97+
dsn: "___PUBLIC_DSN___",
98+
tracesSampleRate: 1.0,
99+
strictTraceContinuation: true,
100+
// Manually provide your organization ID (overrides organization ID parsed from DSN)
101+
orgId: 12345,
102+
});
103+
```
104+
74105
### Disabling Distributed Tracing
75106

76107
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)