Skip to content

Commit b30fda8

Browse files
mydeaLms24lizokm
authored
feat: Add docs about request isolation in Node SDK (#11378)
--------- Co-authored-by: Lukas Stracke <lukas.stracke@sentry.io> Co-authored-by: Liza Mock <liza.mock@sentry.io>
1 parent fdd67ba commit b30fda8

File tree

3 files changed

+59
-0
lines changed
  • docs/platforms/javascript/common/enriching-events
  • platform-includes/enriching-events/scopes/with-isolation-scope

3 files changed

+59
-0
lines changed
Lines changed: 36 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,36 @@
1+
---
2+
title: Request Isolation
3+
description: "Learn more about how request isolation (or process isolation) works in the Sentry SDK."
4+
supported:
5+
- javascript.nextjs
6+
- javascript.node
7+
- javascript.connect
8+
- javascript.express
9+
- javascript.fastify
10+
- javascript.hapi
11+
- javascript.koa
12+
- javascript.nestjs
13+
- javascript.nuxt
14+
- javascript.solidstart
15+
- javascript.sveltekit
16+
- javascript.astro
17+
- javascript.remix
18+
notSupported:
19+
- javascript
20+
---
21+
22+
In server-side environments, the <PlatformLink to='/enriching-events/scopes'>isolation scope</PlatformLink> automatically forks around request boundaries. This is done automatically by the SDK. As a result, each request has its own isolation scope, and data set on the isolation scope only applies to events captured during that request.
23+
24+
However, there are also other times when you may want to have isolation, for example, in background jobs or when you want to isolate a specific part of your code. In these cases, you can use `Sentry.withIsolationScope()` to create a new isolation scope that's valid inside of the callback you pass to it. Learn more about using [withIsolationScope](../scopes/#using-withisolationscope).
25+
26+
The following example shows how you can use `withIsolationScope` to attach data to a specific job run:
27+
28+
```javascript
29+
async function job(jobId) {
30+
return Sentry.withIsolationScope(async () => {
31+
// Only valid for events in this callback
32+
Sentry.setTag("jobId", jobId);
33+
await doSomething();
34+
});
35+
}
36+
```

docs/platforms/javascript/common/enriching-events/scopes/index.mdx

Lines changed: 10 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -143,3 +143,13 @@ In the following example we use <PlatformIdentifier name="with-scope" /> to atta
143143
The scope inside the `withScope()` callback is only valid inside of the callback. Once the callback ends, the scope will be removed and no longer applied. The inner scope is only applied to events that are captured inside of the callback. `withScope()` will clone (or fork) the current scope, so that the current scope is not modified. This allows you to
144144
more easily isolate pieces of context information to specific locations in your code or
145145
even call <PlatformIdentifier name="clear" /> to briefly remove all context information.
146+
147+
<PlatformCategorySection supported={['server']}>
148+
## Using `withIsolationScope`
149+
150+
`withIsolationScope` works fundamentally the same as `withScope`, but it will fork the isolation scope instead of the current scope. Generally, the isolation scope is meant to be forked less frequently than the current scope, and in most cases the SDK will handle this automatically for you.
151+
152+
But in cases where you e.g. want to isolate a non-request process (e.g. a background job), you can use `withIsolationScope` to create a new isolation scope that is only active for the duration of the callback:
153+
154+
<PlatformContent includePath="enriching-events/scopes/with-isolation-scope" />
155+
</PlatformCategorySection>
Lines changed: 13 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,13 @@
1+
```javascript
2+
Sentry.withIsolationScope(function () {
3+
// This user & tag is set inside of this callback
4+
Sentry.setUser({ id: "123" });
5+
Sentry.setTag("my-tag", "my value");
6+
7+
// will be tagged with my-tag="my value" & user
8+
Sentry.captureException(new Error("my error"));
9+
});
10+
11+
// will not be tagged with my-tag & user
12+
Sentry.captureException(new Error("my other error"));
13+
```

0 commit comments

Comments
 (0)