From 0c53967974a4e74d2a7dfcf08e7b4e51e93fdbe1 Mon Sep 17 00:00:00 2001 From: Francesco Novy Date: Tue, 17 Sep 2024 09:32:17 +0200 Subject: [PATCH 1/7] feat: Add docs about process isolation in Node SDK --- .../process-isolation/index.mdx | 47 +++++++++++++++++++ .../common/enriching-events/scopes/index.mdx | 8 ++++ .../with-isolation-scope/javascript.mdx | 13 +++++ 3 files changed, 68 insertions(+) create mode 100644 docs/platforms/javascript/common/enriching-events/process-isolation/index.mdx create mode 100644 platform-includes/enriching-events/scopes/with-isolation-scope/javascript.mdx diff --git a/docs/platforms/javascript/common/enriching-events/process-isolation/index.mdx b/docs/platforms/javascript/common/enriching-events/process-isolation/index.mdx new file mode 100644 index 0000000000000..bb1b110b4fc4b --- /dev/null +++ b/docs/platforms/javascript/common/enriching-events/process-isolation/index.mdx @@ -0,0 +1,47 @@ +--- +title: Process Isolation +description: "Learn more about how process isolation (or request 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 isolation scope is automatically forked around request boundaries. This means that each request will have its own isolation scope, and data set on the isolation scope will only apply to events captured during that request. This is done automatically by the SDK. + +However, the request isolation happens when the request itself is processed. This means that if you e.g. have a middleware where you want to set Sentry data (e.g. `Sentry.setUser()` in an auth middleware), you have to manually fork the isolation scope with `Sentry.withIsolationScope()` - see [Using withIsolationScope](../scopes/#using-withisolationscope). + +This is also necessary if you want to isolate a non-request process, e.g. a background job. + +The following example shows how you can use `withIsolationScope` to attach a user and a tag in an auth middleware: + +```javascript +const auth = (req, res, next) => { + Sentry.withIsolationScope(() => { + const authUser = findUserForHeader(req.headers["authorization"]); + if (!authUser) { + Sentry.setTag("Authenticated", false); + Sentry.setUser(null); + next(new Error("Authentication Error")); + } else { + Sentry.setTag("Authenticated", true); + Sentry.setUser(authUser); + next(); + } + }); +}; +``` + +This way, the user & tag will only be attached to events captured during the request that passed the auth middleware. diff --git a/docs/platforms/javascript/common/enriching-events/scopes/index.mdx b/docs/platforms/javascript/common/enriching-events/scopes/index.mdx index 34ba5fa7a67e6..4890d84af2ef5 100644 --- a/docs/platforms/javascript/common/enriching-events/scopes/index.mdx +++ b/docs/platforms/javascript/common/enriching-events/scopes/index.mdx @@ -143,3 +143,11 @@ In the following example we use 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 to briefly remove all context information. + + +## 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. But in cases where you e.g. want to capture SDK events in a middleware (which happens before the request is processed and thus before the SDKs automatic handling), or if you 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: + + + diff --git a/platform-includes/enriching-events/scopes/with-isolation-scope/javascript.mdx b/platform-includes/enriching-events/scopes/with-isolation-scope/javascript.mdx new file mode 100644 index 0000000000000..cd609f40519e3 --- /dev/null +++ b/platform-includes/enriching-events/scopes/with-isolation-scope/javascript.mdx @@ -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")); +``` From 530fe53ae0ce86eccbdacc2974b1e04e92ad8f05 Mon Sep 17 00:00:00 2001 From: Francesco Novy Date: Wed, 18 Sep 2024 09:57:22 +0200 Subject: [PATCH 2/7] adjust wording --- .../common/enriching-events/process-isolation/index.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/platforms/javascript/common/enriching-events/process-isolation/index.mdx b/docs/platforms/javascript/common/enriching-events/process-isolation/index.mdx index bb1b110b4fc4b..12ac6024cc6dd 100644 --- a/docs/platforms/javascript/common/enriching-events/process-isolation/index.mdx +++ b/docs/platforms/javascript/common/enriching-events/process-isolation/index.mdx @@ -21,7 +21,7 @@ notSupported: In server-side environments, the isolation scope is automatically forked around request boundaries. This means that each request will have its own isolation scope, and data set on the isolation scope will only apply to events captured during that request. This is done automatically by the SDK. -However, the request isolation happens when the request itself is processed. This means that if you e.g. have a middleware where you want to set Sentry data (e.g. `Sentry.setUser()` in an auth middleware), you have to manually fork the isolation scope with `Sentry.withIsolationScope()` - see [Using withIsolationScope](../scopes/#using-withisolationscope). +However, the request isolation happens when the request callback itself is being executed. This means that if you e.g. have a middleware where you want to set Sentry data (e.g. `Sentry.setUser()` in an auth middleware), you have to manually fork the isolation scope with `Sentry.withIsolationScope()` - see [Using withIsolationScope](../scopes/#using-withisolationscope). This is also necessary if you want to isolate a non-request process, e.g. a background job. From c7c6896bf63d8091595ceec9a202dc5b514a36cf Mon Sep 17 00:00:00 2001 From: Francesco Novy Date: Wed, 18 Sep 2024 10:20:09 +0200 Subject: [PATCH 3/7] adjust example --- .../process-isolation/index.mdx | 27 ++++++------------- 1 file changed, 8 insertions(+), 19 deletions(-) diff --git a/docs/platforms/javascript/common/enriching-events/process-isolation/index.mdx b/docs/platforms/javascript/common/enriching-events/process-isolation/index.mdx index 12ac6024cc6dd..6583bcb4cb6a8 100644 --- a/docs/platforms/javascript/common/enriching-events/process-isolation/index.mdx +++ b/docs/platforms/javascript/common/enriching-events/process-isolation/index.mdx @@ -21,27 +21,16 @@ notSupported: In server-side environments, the isolation scope is automatically forked around request boundaries. This means that each request will have its own isolation scope, and data set on the isolation scope will only apply to events captured during that request. This is done automatically by the SDK. -However, the request isolation happens when the request callback itself is being executed. This means that if you e.g. have a middleware where you want to set Sentry data (e.g. `Sentry.setUser()` in an auth middleware), you have to manually fork the isolation scope with `Sentry.withIsolationScope()` - see [Using withIsolationScope](../scopes/#using-withisolationscope). +However, tehre are also other cases where 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 is valid inside of the callback you pass to it - see [Using withIsolationScope](../scopes/#using-withisolationscope). -This is also necessary if you want to isolate a non-request process, e.g. a background job. - -The following example shows how you can use `withIsolationScope` to attach a user and a tag in an auth middleware: +The following example shows how you can use `withIsolationScope` to attach data for a specific job run: ```javascript -const auth = (req, res, next) => { - Sentry.withIsolationScope(() => { - const authUser = findUserForHeader(req.headers["authorization"]); - if (!authUser) { - Sentry.setTag("Authenticated", false); - Sentry.setUser(null); - next(new Error("Authentication Error")); - } else { - Sentry.setTag("Authenticated", true); - Sentry.setUser(authUser); - next(); - } +async function job(jobId) { + return Sentry.withIsolationScope(async () => { + // Only valid for events in this callback + Sentry.setTag("jobId", jobId); + await doSomething(); }); -}; +} ``` - -This way, the user & tag will only be attached to events captured during the request that passed the auth middleware. From f8706780eb6f5835ff730cef38f715dace2918fe Mon Sep 17 00:00:00 2001 From: Francesco Novy Date: Wed, 18 Sep 2024 11:06:01 +0200 Subject: [PATCH 4/7] Update docs/platforms/javascript/common/enriching-events/process-isolation/index.mdx Co-authored-by: Lukas Stracke --- .../common/enriching-events/process-isolation/index.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/platforms/javascript/common/enriching-events/process-isolation/index.mdx b/docs/platforms/javascript/common/enriching-events/process-isolation/index.mdx index 6583bcb4cb6a8..09a8f9ddc566f 100644 --- a/docs/platforms/javascript/common/enriching-events/process-isolation/index.mdx +++ b/docs/platforms/javascript/common/enriching-events/process-isolation/index.mdx @@ -21,7 +21,7 @@ notSupported: In server-side environments, the isolation scope is automatically forked around request boundaries. This means that each request will have its own isolation scope, and data set on the isolation scope will only apply to events captured during that request. This is done automatically by the SDK. -However, tehre are also other cases where 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 is valid inside of the callback you pass to it - see [Using withIsolationScope](../scopes/#using-withisolationscope). +However, there are also other cases where 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 is valid inside of the callback you pass to it - see [Using withIsolationScope](../scopes/#using-withisolationscope). The following example shows how you can use `withIsolationScope` to attach data for a specific job run: From 45528a943257114ed80757e1c7c217952bcd68d2 Mon Sep 17 00:00:00 2001 From: Francesco Novy Date: Thu, 10 Oct 2024 09:28:05 +0200 Subject: [PATCH 5/7] Apply suggestions from code review Co-authored-by: Liza Mock --- .../common/enriching-events/process-isolation/index.mdx | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/docs/platforms/javascript/common/enriching-events/process-isolation/index.mdx b/docs/platforms/javascript/common/enriching-events/process-isolation/index.mdx index 09a8f9ddc566f..7f64348e83c36 100644 --- a/docs/platforms/javascript/common/enriching-events/process-isolation/index.mdx +++ b/docs/platforms/javascript/common/enriching-events/process-isolation/index.mdx @@ -19,11 +19,11 @@ notSupported: - javascript --- -In server-side environments, the isolation scope is automatically forked around request boundaries. This means that each request will have its own isolation scope, and data set on the isolation scope will only apply to events captured during that request. This is done automatically by the SDK. +In server-side environments, the isolation scope 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 cases where 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 is valid inside of the callback you pass to it - see [Using withIsolationScope](../scopes/#using-withisolationscope). +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 for a specific job run: +The following example shows how you can use `withIsolationScope` to attach data to a specific job run: ```javascript async function job(jobId) { From fce2ca4ac838f5b5104230911d81994ad60eb1b4 Mon Sep 17 00:00:00 2001 From: Francesco Novy Date: Thu, 10 Oct 2024 09:26:37 +0200 Subject: [PATCH 6/7] rename to request isolation --- .../{process-isolation => request-isolation}/index.mdx | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) rename docs/platforms/javascript/common/enriching-events/{process-isolation => request-isolation}/index.mdx (94%) diff --git a/docs/platforms/javascript/common/enriching-events/process-isolation/index.mdx b/docs/platforms/javascript/common/enriching-events/request-isolation/index.mdx similarity index 94% rename from docs/platforms/javascript/common/enriching-events/process-isolation/index.mdx rename to docs/platforms/javascript/common/enriching-events/request-isolation/index.mdx index 7f64348e83c36..bafd5765f24e1 100644 --- a/docs/platforms/javascript/common/enriching-events/process-isolation/index.mdx +++ b/docs/platforms/javascript/common/enriching-events/request-isolation/index.mdx @@ -1,6 +1,6 @@ --- -title: Process Isolation -description: "Learn more about how process isolation (or request isolation) works in the Sentry SDK." +title: Request Isolation +description: "Learn more about how request isolation (or process isolation) works in the Sentry SDK." supported: - javascript.nextjs - javascript.node From 41d0ad7cfde3ad685d753f9c0650d45b7965a1ba Mon Sep 17 00:00:00 2001 From: Francesco Novy Date: Thu, 10 Oct 2024 09:29:52 +0200 Subject: [PATCH 7/7] PR feedback --- .../javascript/common/enriching-events/scopes/index.mdx | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) diff --git a/docs/platforms/javascript/common/enriching-events/scopes/index.mdx b/docs/platforms/javascript/common/enriching-events/scopes/index.mdx index 4890d84af2ef5..bc0d760424270 100644 --- a/docs/platforms/javascript/common/enriching-events/scopes/index.mdx +++ b/docs/platforms/javascript/common/enriching-events/scopes/index.mdx @@ -147,7 +147,9 @@ even call to briefly remove all context info ## 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. But in cases where you e.g. want to capture SDK events in a middleware (which happens before the request is processed and thus before the SDKs automatic handling), or if you 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: +`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. + +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: