Add docs for browserSessionIntegration and `trackIncomingRequestsAs…

…Sessions` as alternative to `autoSessionTracking` in JS SDKs
getsentry · Dec 5, 2024 · e94bf2f · e94bf2f
1 parent c0fcbc6
commit e94bf2f
Show file tree

Hide file tree

Showing 17 changed files with 123 additions and 20 deletions.
diff --git a/docs/platforms/javascript/common/configuration/integrations/browsersession.mdx b/docs/platforms/javascript/common/configuration/integrations/browsersession.mdx
@@ -0,0 +1,39 @@
+---
+title: BrowserSession
+description: "Track healthy Sessions in the Browser."
+notSupported:
+  - javascript.cordova
+  - javascript.node
+  - javascript.aws-lambda
+  - javascript.azure-functions
+  - javascript.connect
+  - javascript.express
+  - javascript.fastify
+  - javascript.gcp-functions
+  - javascript.hapi
+  - javascript.koa
+  - javascript.nestjs
+  - javascript.deno
+  - javascript.cloudflare
+  - javascript.bun
+---
+
+<Alert level="info">
+
+This integration only works inside a browser environment.
+
+</Alert>
+
+_Import name: `Sentry.browserSessionIntegration`_
+
+Sentry's [Release Health](/product/releases/health/) feature allows you to track user adoption and your application's crash-free rate.
+
+The BrowserSession integration will create a Session that is used to track the health of your release when the user loads your page or application.
+Sessions will be marked as faulty when an error is captured while a Session is active.
+Read more about <PlatformLink to="/configuration/releases/#sessions">Sessions</PlatformLink>.
+
+```JavaScript
+Sentry.init({
+  integrations: [Sentry.browserSessionIntegration()],
+});
+```
diff --git a/docs/platforms/javascript/common/configuration/integrations/http.mdx b/docs/platforms/javascript/common/configuration/integrations/http.mdx
@@ -73,6 +73,13 @@ The callback function receives two arguments:
 - `urlPath`: The URL path of the incoming request, including the query string if available. For example: `/users?name=John`.
 - `request`: An object of type `IncomingMessage` containing the incoming request. You can use this to filter on properties like the request method or headers.
 
+### `trackIncomingRequestsAsSessions`
+
+_Type: `boolean`_ (Defaults to `true`)
+
+Whether the integration should create [Sessions](/product/releases/health/#sessions) for incoming requests to track the health and crash-free rate of your releases in Sentry.
+Read more about [Release Health](/product/releases/health/).
+
 ### `instrumentation`
 
 You can also pass some hooks through to the [underlying OpenTelemetry Instrumentation](https://www.npmjs.com/package/@opentelemetry/instrumentation-http):

diff --git a/docs/platforms/javascript/common/configuration/options.mdx b/docs/platforms/javascript/common/configuration/options.mdx
@@ -41,12 +41,14 @@ Turns debug mode on or off. If debug is enabled SDK will attempt to print out us
 
 Sets the release. Some SDKs will try to automatically configure a release out of the box but it's a better idea to manually set it to guarantee that the release is in sync with your deploy integrations or source map uploads. Release names are strings, but some formats are detected by Sentry and might be rendered differently. Learn more about how to send release data so Sentry can tell you about regressions between releases and identify the potential source in [the releases documentation](/product/releases/) or the <SandboxLink scenario="releases">sandbox</SandboxLink>.
 
-<PlatformCategorySection supported={['server', 'serverless']}>
-By default the SDK will try to read this value from the `SENTRY_RELEASE` environment variable.
+<PlatformCategorySection supported={["server", "serverless"]}>
+  By default the SDK will try to read this value from the `SENTRY_RELEASE`
+  environment variable.
 </PlatformCategorySection>
 
-<PlatformCategorySection supported={['browser']}>
-By default the SDK will try to read this value from `window.SENTRY_RELEASE.id` if available.
+<PlatformCategorySection supported={["browser"]}>
+  By default the SDK will try to read this value from `window.SENTRY_RELEASE.id`
+  if available.
 </PlatformCategorySection>
 
 <PlatformSection supported={["javascript.electron"]}>
@@ -102,9 +104,10 @@ Grouping in Sentry is different for events with stack traces and without. As a r
 <PlatformCategorySection supported={['server', 'serverless']}>
 <ConfigKey name="server-name">
 
-  This option can be used to supply a "server name." When provided, the name of the server is sent along and persisted in the event. For many integrations, the server name actually corresponds to the device hostname, even in situations where the machine is not actually a server.
+This option can be used to supply a "server name." When provided, the name of the server is sent along and persisted in the event. For many integrations, the server name actually corresponds to the device hostname, even in situations where the machine is not actually a server.
+
+Most SDKs will attempt to auto-discover this value.
 
-  Most SDKs will attempt to auto-discover this value.
 </ConfigKey>
 
 </PlatformCategorySection>
@@ -141,6 +144,15 @@ Grouping in Sentry is different for events with stack traces and without. As a r
 
 Defaults to `true`. When set to `true`, the SDK will send session events to Sentry. This is supported in all browser SDKs, emitting one session per pageload and page navigation to Sentry. In mobile SDKs, when the app goes to the background for longer than 30 seconds, sessions are ended.
 
+<Alert title="Deprecation Notice">
+
+{/* We don't use platform links here because we always have to link to node and browser here and doing a conditional just for that feels overkill. */}
+
+The `autoSessionTracking` option is deprecated from SDK version `8.43.0` onwards.
+Instead, use the [BrowserSession integration](/platforms/javascript/configuration/integrations/browsersession/) for the Browser and the [Http integration](/platforms/javascript/guides/node/configuration/integrations/http/) (via the `trackIncomingRequestsAsSessions` option) for the Node.js runtime.
+
+</Alert>
+
 </ConfigKey>
 
 <ConfigKey name="auto-session-tracking" supported={["javascript.electron"]} >
@@ -155,7 +167,6 @@ Data to be set to the initial scope. Initial scope can be defined either as an o
 
 Object:
 
-
 ```javascript
 Sentry.init({
   dsn: "___PUBLIC_DSN___",
@@ -316,17 +327,20 @@ Switches out the transport used to send events. How this works depends on the SD
 
 Options used to configure the transport. This is an object with the following possible optional keys:
 
-<PlatformCategorySection supported={['server', 'serverless']}>
-- `headers`: An object containing headers to be sent with every request.
-- `proxy`: A proxy used for outbound requests. Can be http or https.
-- `caCerts`: A path or list of paths to a CA certificate, or a buffer of CA certificates.
-- `httpModule`: A custom HTTP module to use for requests. Defaults to the the native `http` and `https` modules.
-- `keepAlive`: Determines whether to keep the socket alive between requests. Defaults to `false`.
+<PlatformCategorySection supported={["server", "serverless"]}>
+  - `headers`: An object containing headers to be sent with every request. -
+  `proxy`: A proxy used for outbound requests. Can be http or https. -
+  `caCerts`: A path or list of paths to a CA certificate, or a buffer of CA
+  certificates. - `httpModule`: A custom HTTP module to use for requests.
+  Defaults to the the native `http` and `https` modules. - `keepAlive`:
+  Determines whether to keep the socket alive between requests. Defaults to
+  `false`.
 </PlatformCategorySection>
 
-<PlatformCategorySection supported={['browser', 'desktop']}>
-- `headers`: An object containing headers to be sent with every request. Used by the SDK's fetch and XHR transports.
-- `fetchOptions`: An object containing options to be passed to the `fetch` call. Used by the SDK's fetch transport.
+<PlatformCategorySection supported={["browser", "desktop"]}>
+  - `headers`: An object containing headers to be sent with every request. Used
+  by the SDK's fetch and XHR transports. - `fetchOptions`: An object containing
+  options to be passed to the `fetch` call. Used by the SDK's fetch transport.
 </PlatformCategorySection>
 
 </ConfigKey>

diff --git a/...ms/javascript/guides/electron/configuration/integrations/mainprocesssession.mdx b/...ms/javascript/guides/electron/configuration/integrations/mainprocesssession.mdx
@@ -12,8 +12,9 @@ use the <PlatformLink
 to="/configuration/integrations/browserwindowsession">BrowserWindowSession</PlatformLink>
 integration in the renderer processes.
 
-Unless `autoSessionTracking` is set to `false`, this integration will be automatically added.
+{/* TODO(v9): When electron does a new major, update this since autoSessionTracking got removed */}
 
+Unless `autoSessionTracking` is set to `false`, this integration will be automatically added.
 
 ```javascript
 import * as Sentry from "@sentry/electron/main";
@@ -31,8 +32,6 @@ import * as Sentry from "@sentry/electron/main";
 
 Sentry.init({
   dsn: "___PUBLIC_DSN___",
-  integrations: [
-    Sentry.mainProcessSessionIntegration({ sendOnCreate: true }),
-  ],
+  integrations: [Sentry.mainProcessSessionIntegration({ sendOnCreate: true })],
 });
 ```
diff --git a/platform-includes/configuration/auto-session-tracking/javascript.electron.mdx b/platform-includes/configuration/auto-session-tracking/javascript.electron.mdx
@@ -10,6 +10,8 @@ Due to the nature of `crashed` and `abnormal` exits, these sessions are finished
 
 To receive data on user adoption, such as users crash free rate percentage, and the number of users that have adopted a specific release, set the user on the [`initialScope`](/platforms/javascript/configuration/options/#initial-scope) when initializing the SDK.
 
+{/* TODO(v9): When electron does a new major, update this since autoSessionTracking got removed */}
+
 To disable sending sessions, set the `autoSessionTracking` flag to `false`:
 
 ```javascript

diff --git a/platform-includes/configuration/auto-session-tracking/javascript.mdx b/platform-includes/configuration/auto-session-tracking/javascript.mdx
@@ -1,3 +1,5 @@
+{/* TODO(v9): Update this for the new behaviour (sessions are persisted in sessionStorage or memory) */}
+
 We create a session for every page load. For single-page applications, we will create a new session for every navigation change (History API).
 
 We mark the session as:
@@ -14,3 +16,18 @@ Sentry.init({
   autoSessionTracking: false, // default: true
 });
 ```
+
+{/* TODO(v9): Remove this notice? */}
+
+<PlatformSection notSupported={["javacript.cordova", "javascript.capacitor", "javascript.electron"]}>
+
+<Alert title="Deprecation Notice">
+
+{/* We don't use platform links here because we always have to link to node and browser here and doing a conditional just for that feels overkill. */}
+
+The `autoSessionTracking` option is deprecated from SDK version `8.43.0` onwards.
+Instead, use the [BrowserSession integration](/platforms/javascript/configuration/integrations/browsersession/) for the Browser and the [Http integration](/platforms/javascript/guides/node/configuration/integrations/http/) (via the `trackIncomingRequestsAsSessions` option) for the Node.js runtime.
+
+</Alert>
+
+</PlatformSection>
diff --git a/platform-includes/configuration/auto-session-tracking/javascript.node.mdx b/platform-includes/configuration/auto-session-tracking/javascript.node.mdx
@@ -14,3 +14,18 @@ Sentry.init({
   autoSessionTracking: false, // default: true
 });
 ```
+
+{/* TODO(v9): Remove this notice? */}
+
+<PlatformSection notSupported={["javacript.cordova", "javascript.capacitor", "javascript.electron"]}>
+
+<Alert title="Deprecation Notice">
+
+{/* We don't use platform links here because we always have to link to node and browser here and doing a conditional just for that feels overkill. */}
+
+The `autoSessionTracking` option is deprecated from SDK version `8.43.0` onwards.
+Instead, use the [BrowserSession integration](/platforms/javascript/configuration/integrations/browsersession/) for the Browser and the [Http integration](/platforms/javascript/guides/node/configuration/integrations/http/) (via the `trackIncomingRequestsAsSessions` option) for the Node.js runtime.
+
+</Alert>
+
+</PlatformSection>
diff --git a/platform-includes/configuration/integrations/javascript.astro.mdx b/platform-includes/configuration/integrations/javascript.astro.mdx
@@ -30,6 +30,7 @@ Depending on whether an integration enhances the functionality of a particular r
 | [`globalHandlersIntegration`](./globalhandlers)       |        ✓         |     ✓      |             |            |                        |
 | [`httpContextIntegration`](./httpcontext)             |        ✓         |            |             |            |           ✓            |
 | [`browserProfilingIntegration`](./browserprofiling)   |                  |            |      ✓      |            |                        |
+| [`browserSessionIntegration`](./browsersession)       |        ✓         |            |             |            |           ✓            |
 | [`contextLinesIntegration`](./contextlines)           |                  |     ✓      |             |            |                        |
 | [`httpClientIntegration`](./httpclient)               |                  |     ✓      |             |            |                        |
 | [`moduleMetadataIntegration`](./modulemetadata)       |                  |            |             |            |           ✓            |

diff --git a/platform-includes/configuration/integrations/javascript.gatsby.mdx b/platform-includes/configuration/integrations/javascript.gatsby.mdx
@@ -11,6 +11,7 @@
 | [`inboundFiltersIntegration`](./inboundfilters)       |        ✓         |     ✓      |             |            |                        |
 | [`linkedErrorsIntegration`](./linkederrors)           |        ✓         |     ✓      |             |            |                        |
 | [`browserProfilingIntegration`](./browserprofiling)   |                  |            |      ✓      |            |                        |
+| [`browserSessionIntegration`](./browsersession)       |        ✓         |            |             |            |           ✓            |
 | [`browserTracingIntegration`](./browsertracing)       |                  |            |      ✓      |            |           ✓            |
 | [`captureConsoleIntegration`](./captureconsole)       |                  |            |             |            |           ✓            |
 | [`contextLinesIntegration`](./contextlines)           |                  |     ✓      |             |            |                        |

diff --git a/platform-includes/configuration/integrations/javascript.mdx b/platform-includes/configuration/integrations/javascript.mdx
@@ -11,6 +11,7 @@
 | [`inboundFiltersIntegration`](./inboundfilters)       |        ✓         |     ✓      |             |            |                        |
 | [`linkedErrorsIntegration`](./linkederrors)           |        ✓         |     ✓      |             |            |                        |
 | [`browserProfilingIntegration`](./browserprofiling)   |                  |            |      ✓      |            |                        |
+| [`browserSessionIntegration`](./browsersession)       |        ✓         |            |             |            |           ✓            |
 | [`browserTracingIntegration`](./browsertracing)       |                  |            |      ✓      |            |           ✓            |
 | [`captureConsoleIntegration`](./captureconsole)       |                  |            |             |            |           ✓            |
 | [`contextLinesIntegration`](./contextlines)           |                  |     ✓      |             |            |                        |

diff --git a/platform-includes/configuration/integrations/javascript.nextjs.mdx b/platform-includes/configuration/integrations/javascript.nextjs.mdx
@@ -31,6 +31,7 @@ Depending on whether an integration enhances the functionality of a particular r
 | [`globalHandlersIntegration`](./globalhandlers)       |        ✓         |     ✓      |             |            |                        |
 | [`httpContextIntegration`](./httpcontext)             |        ✓         |            |             |            |           ✓            |
 | [`browserProfilingIntegration`](./browserprofiling)   |                  |            |      ✓      |            |                        |
+| [`browserSessionIntegration`](./browsersession)       |        ✓         |            |             |            |           ✓            |
 | [`contextLinesIntegration`](./contextlines)           |                  |     ✓      |             |            |                        |
 | [`httpClientIntegration`](./httpclient)               |                  |     ✓      |             |            |                        |
 | [`moduleMetadataIntegration`](./modulemetadata)       |                  |            |             |            |           ✓            |

diff --git a/platform-includes/configuration/integrations/javascript.nuxt.mdx b/platform-includes/configuration/integrations/javascript.nuxt.mdx
@@ -30,6 +30,7 @@ Depending on whether an integration enhances the functionality of a particular r
 | [`globalHandlersIntegration`](./globalhandlers)       |        ✓         |     ✓      |             |            |                        |
 | [`httpContextIntegration`](./httpcontext)             |        ✓         |            |             |            |           ✓            |
 | [`browserProfilingIntegration`](./browserprofiling)   |                  |            |      ✓      |            |                        |
+| [`browserSessionIntegration`](./browsersession)       |        ✓         |            |             |            |           ✓            |
 | [`contextLinesIntegration`](./contextlines)           |                  |     ✓      |             |            |                        |
 | [`httpClientIntegration`](./httpclient)               |                  |     ✓      |             |            |                        |
 | [`moduleMetadataIntegration`](./modulemetadata)       |                  |            |             |            |           ✓            |

diff --git a/platform-includes/configuration/integrations/javascript.remix.mdx b/platform-includes/configuration/integrations/javascript.remix.mdx
@@ -30,6 +30,7 @@ Depending on whether an integration enhances the functionality of a particular r
 | [`globalHandlersIntegration`](./globalhandlers)       |        ✓         |     ✓      |             |            |                        |
 | [`httpContextIntegration`](./httpcontext)             |        ✓         |            |             |            |           ✓            |
 | [`browserProfilingIntegration`](./browserprofiling)   |                  |            |      ✓      |            |                        |
+| [`browserSessionIntegration`](./browsersession)       |        ✓         |            |             |            |           ✓            |
 | [`contextLinesIntegration`](./contextlines)           |                  |     ✓      |             |            |                        |
 | [`httpClientIntegration`](./httpclient)               |                  |     ✓      |             |            |                        |
 | [`moduleMetadataIntegration`](./modulemetadata)       |                  |            |             |            |           ✓            |

diff --git a/platform-includes/configuration/integrations/javascript.solidstart.mdx b/platform-includes/configuration/integrations/javascript.solidstart.mdx
@@ -30,6 +30,7 @@ Depending on whether an integration enhances the functionality of a particular r
 | [`globalHandlersIntegration`](./globalhandlers)       |        ✓         |     ✓      |             |            |                        |
 | [`httpContextIntegration`](./httpcontext)             |        ✓         |            |             |            |           ✓            |
 | [`browserProfilingIntegration`](./browserprofiling)   |                  |            |      ✓      |            |                        |
+| [`browserSessionIntegration`](./browsersession)       |        ✓         |            |             |            |           ✓            |
 | [`contextLinesIntegration`](./contextlines)           |                  |     ✓      |             |            |                        |
 | [`httpClientIntegration`](./httpclient)               |                  |     ✓      |             |            |                        |
 | [`moduleMetadataIntegration`](./modulemetadata)       |                  |            |             |            |           ✓            |

diff --git a/platform-includes/configuration/integrations/javascript.sveltekit.mdx b/platform-includes/configuration/integrations/javascript.sveltekit.mdx
@@ -30,6 +30,7 @@ Depending on whether an integration enhances the functionality of a particular r
 | [`globalHandlersIntegration`](./globalhandlers)       |        ✓         |     ✓      |             |            |                        |
 | [`httpContextIntegration`](./httpcontext)             |        ✓         |            |             |            |           ✓            |
 | [`browserProfilingIntegration`](./browserprofiling)   |                  |            |      ✓      |            |                        |
+| [`browserSessionIntegration`](./browsersession)       |        ✓         |            |             |            |           ✓            |
 | [`contextLinesIntegration`](./contextlines)           |                  |     ✓      |             |            |                        |
 | [`httpClientIntegration`](./httpclient)               |                  |     ✓      |             |            |                        |
 | [`moduleMetadataIntegration`](./modulemetadata)       |                  |            |             |            |           ✓            |