Skip to content
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.

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

feat: Add docs about request isolation in Node SDK #11378

Merged
merged 7 commits into from
Oct 10, 2024
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
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
Original file line number Diff line number Diff line change
@@ -0,0 +1,36 @@
---
title: Request Isolation
description: "Learn more about how request isolation (or process isolation) works in the Sentry SDK."
supported:
- javascript.nextjs
- javascript.node
- javascript.connect
- javascript.express
- javascript.fastify
- javascript.hapi
- javascript.koa
- javascript.nestjs
- javascript.nuxt
- javascript.solidstart
- javascript.sveltekit
- javascript.astro
- javascript.remix
notSupported:
- javascript
---

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.

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

The following example shows how you can use `withIsolationScope` to attach data to a specific job run:

```javascript
async function job(jobId) {
return Sentry.withIsolationScope(async () => {
// Only valid for events in this callback
Sentry.setTag("jobId", jobId);
await doSomething();
});
}
```
10 changes: 10 additions & 0 deletions docs/platforms/javascript/common/enriching-events/scopes/index.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -143,3 +143,13 @@ In the following example we use <PlatformIdentifier name="with-scope" /> to atta
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
more easily isolate pieces of context information to specific locations in your code or
even call <PlatformIdentifier name="clear" /> to briefly remove all context information.

<PlatformCategorySection supported={['server']}>
## Using `withIsolationScope`

`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.
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

For a person who is not very familiar with Sentry SDK, this sentence is probably too dense for me. I know what request isolation and isolating scopes are but what exactly is "forking a scope". What is the current scope and how it is determined? Why is is meant to be forked less frequently and how is it relevant to me or this conversation? What are those "most cases" where the SDK handles for me. At least what kind of cases are meant to be automatically handled?

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

we (try to) explain these things in the page above this section (see https://docs.sentry.io/platforms/javascript/guides/node/enriching-events/scopes/). I do agree that all of this is not super easy to understand, feel free to PR changes to wording to this!

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I do agree that all of this is not super easy to understand, feel free to PR changes to wording to this!

That's the thing! I would love to but I 100% don't understand what's going on. The questions I raised in my first comment are questions I don't know the answers to 😅


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:

<PlatformContent includePath="enriching-events/scopes/with-isolation-scope" />
</PlatformCategorySection>
Original file line number Diff line number Diff line change
@@ -0,0 +1,13 @@
```javascript
Sentry.withIsolationScope(function () {
// This user & tag is set inside of this callback
Sentry.setUser({ id: "123" });
Sentry.setTag("my-tag", "my value");

// will be tagged with my-tag="my value" & user
Sentry.captureException(new Error("my error"));
});

// will not be tagged with my-tag & user
Sentry.captureException(new Error("my other error"));
```
Loading