Skip to content

Commit 1ea4fd7

Browse files
lforstlizokm
authored and
Lms24
committed
Add docs for browserSessionIntegration and trackIncomingRequestsAsSessions as alternative to autoSessionTracking in JS SDKs (#12056)
Co-authored-by: Liza Mock <[email protected]>
1 parent 2de63b5 commit 1ea4fd7

File tree

17 files changed

+117
-20
lines changed

17 files changed

+117
-20
lines changed

‎docs/platforms/javascript/common/configuration/integrations/browsersession.mdx

Lines changed: 37 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,37 @@
1+
---
2+
title: BrowserSession
3+
description: "Track healthy Sessions in the Browser."
4+
notSupported:
5+
- javascript.cordova
6+
- javascript.node
7+
- javascript.aws-lambda
8+
- javascript.azure-functions
9+
- javascript.connect
10+
- javascript.express
11+
- javascript.fastify
12+
- javascript.gcp-functions
13+
- javascript.hapi
14+
- javascript.koa
15+
- javascript.nestjs
16+
- javascript.deno
17+
- javascript.cloudflare
18+
- javascript.bun
19+
---
20+
21+
<Alert level="info">
22+
23+
This integration only works inside a browser environment.
24+
25+
</Alert>
26+
27+
_Import name: `Sentry.browserSessionIntegration`_
28+
29+
Sentry's [Release Health](/product/releases/health/) feature allows you to track user adoption and your application's crash-free rate.
30+
When the BrowserSession integration is enabled, it automatically creates a session each time a user loads your page or application. These sessions are used to track your release health. If an error is captured during an active session, the session will be flagged as faulty.
31+
Read more about <PlatformLink to="/configuration/releases/#sessions">Sessions</PlatformLink>.
32+
33+
```JavaScript
34+
Sentry.init({
35+
integrations: [Sentry.browserSessionIntegration()],
36+
});
37+
```

‎docs/platforms/javascript/common/configuration/integrations/http.mdx

Lines changed: 7 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -73,6 +73,13 @@ The callback function receives two arguments:
7373
- `urlPath`: The URL path of the incoming request, including the query string if available. For example: `/users?name=John`.
7474
- `request`: An object of type `IncomingMessage` containing the incoming request. You can use this to filter on properties like the request method or headers.
7575

76+
### `trackIncomingRequestsAsSessions`
77+
78+
_Type: `boolean`_ (Defaults to `true`)
79+
80+
Determines 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.
81+
Read more about [Release Health](/product/releases/health/).
82+
7683
### `instrumentation`
7784

7885
You can also pass some hooks through to the [underlying OpenTelemetry Instrumentation](https://www.npmjs.com/package/@opentelemetry/instrumentation-http):

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

Lines changed: 28 additions & 16 deletions
Original file line numberDiff line numberDiff line change
@@ -41,12 +41,14 @@ Turns debug mode on or off. If debug is enabled SDK will attempt to print out us
4141

4242
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>.
4343

44-
<PlatformCategorySection supported={['server', 'serverless']}>
45-
By default the SDK will try to read this value from the `SENTRY_RELEASE` environment variable.
44+
<PlatformCategorySection supported={["server", "serverless"]}>
45+
By default, the SDK will try to read this value from the `SENTRY_RELEASE`
46+
environment variable.
4647
</PlatformCategorySection>
4748

48-
<PlatformCategorySection supported={['browser']}>
49-
By default the SDK will try to read this value from `window.SENTRY_RELEASE.id` if available.
49+
<PlatformCategorySection supported={["browser"]}>
50+
By default, the SDK will try to read this value from `window.SENTRY_RELEASE.id`
51+
if available.
5052
</PlatformCategorySection>
5153

5254
<PlatformSection supported={["javascript.electron"]}>
@@ -102,9 +104,10 @@ Grouping in Sentry is different for events with stack traces and without. As a r
102104
<PlatformCategorySection supported={['server', 'serverless']}>
103105
<ConfigKey name="server-name">
104106

105-
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.
107+
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.
108+
109+
Most SDKs will attempt to auto-discover this value.
106110

107-
Most SDKs will attempt to auto-discover this value.
108111
</ConfigKey>
109112

110113
</PlatformCategorySection>
@@ -141,6 +144,13 @@ Grouping in Sentry is different for events with stack traces and without. As a r
141144

142145
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.
143146

147+
<Alert title="Deprecation Notice">
148+
149+
{/* 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. */}
150+
Starting with SDK version 8.43.0 and up, the `autoSessionTracking` option has been deprecated. You can use the [BrowserSession integration](/platforms/javascript/configuration/integrations/browsersession/) in browser environments and the [Http integration](/platforms/javascript/guides/node/configuration/integrations/http/) (via the `trackIncomingRequestsAsSessions` option) in Node.js runtime.
151+
152+
</Alert>
153+
144154
</ConfigKey>
145155

146156
<ConfigKey name="auto-session-tracking" supported={["javascript.electron"]} >
@@ -155,7 +165,6 @@ Data to be set to the initial scope. Initial scope can be defined either as an o
155165

156166
Object:
157167

158-
159168
```javascript
160169
Sentry.init({
161170
dsn: "___PUBLIC_DSN___",
@@ -316,17 +325,20 @@ Switches out the transport used to send events. How this works depends on the SD
316325

317326
Options used to configure the transport. This is an object with the following possible optional keys:
318327

319-
<PlatformCategorySection supported={['server', 'serverless']}>
320-
- `headers`: An object containing headers to be sent with every request.
321-
- `proxy`: A proxy used for outbound requests. Can be http or https.
322-
- `caCerts`: A path or list of paths to a CA certificate, or a buffer of CA certificates.
323-
- `httpModule`: A custom HTTP module to use for requests. Defaults to the the native `http` and `https` modules.
324-
- `keepAlive`: Determines whether to keep the socket alive between requests. Defaults to `false`.
328+
<PlatformCategorySection supported={["server", "serverless"]}>
329+
- `headers`: An object containing headers to be sent with every request. -
330+
`proxy`: A proxy used for outbound requests. Can be http or https. -
331+
`caCerts`: A path or list of paths to a CA certificate, or a buffer of CA
332+
certificates. - `httpModule`: A custom HTTP module to use for requests.
333+
Defaults to the the native `http` and `https` modules. - `keepAlive`:
334+
Determines whether to keep the socket alive between requests. Defaults to
335+
`false`.
325336
</PlatformCategorySection>
326337

327-
<PlatformCategorySection supported={['browser', 'desktop']}>
328-
- `headers`: An object containing headers to be sent with every request. Used by the SDK's fetch and XHR transports.
329-
- `fetchOptions`: An object containing options to be passed to the `fetch` call. Used by the SDK's fetch transport.
338+
<PlatformCategorySection supported={["browser", "desktop"]}>
339+
- `headers`: An object containing headers to be sent with every request. Used
340+
by the SDK's fetch and XHR transports. - `fetchOptions`: An object containing
341+
options to be passed to the `fetch` call. Used by the SDK's fetch transport.
330342
</PlatformCategorySection>
331343

332344
</ConfigKey>

‎docs/platforms/javascript/guides/electron/configuration/integrations/mainprocesssession.mdx

Lines changed: 3 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -12,8 +12,9 @@ use the <PlatformLink
1212
to="/configuration/integrations/browserwindowsession">BrowserWindowSession</PlatformLink>
1313
integration in the renderer processes.
1414

15-
Unless `autoSessionTracking` is set to `false`, this integration will be automatically added.
15+
{/* TODO(v9): When electron does a new major, update this since autoSessionTracking got removed */}
1616

17+
Unless `autoSessionTracking` is set to `false`, this integration will be automatically added.
1718

1819
```javascript
1920
import * as Sentry from "@sentry/electron/main";
@@ -31,8 +32,6 @@ import * as Sentry from "@sentry/electron/main";
3132

3233
Sentry.init({
3334
dsn: "___PUBLIC_DSN___",
34-
integrations: [
35-
Sentry.mainProcessSessionIntegration({ sendOnCreate: true }),
36-
],
35+
integrations: [Sentry.mainProcessSessionIntegration({ sendOnCreate: true })],
3736
});
3837
```

‎platform-includes/configuration/auto-session-tracking/javascript.electron.mdx

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -10,6 +10,8 @@ Due to the nature of `crashed` and `abnormal` exits, these sessions are finished
1010

1111
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.
1212

13+
{/* TODO(v9): When electron does a new major, update this since autoSessionTracking got removed */}
14+
1315
To disable sending sessions, set the `autoSessionTracking` flag to `false`:
1416

1517
```javascript

‎platform-includes/configuration/auto-session-tracking/javascript.mdx

Lines changed: 16 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1,3 +1,5 @@
1+
{/* TODO(v9): Update this for the new behaviour (sessions are persisted in sessionStorage or memory) */}
2+
13
We create a session for every page load. For single-page applications, we will create a new session for every navigation change (History API).
24

35
We mark the session as:
@@ -14,3 +16,17 @@ Sentry.init({
1416
autoSessionTracking: false, // default: true
1517
});
1618
```
19+
20+
{/* TODO(v9): Remove this notice? */}
21+
22+
<PlatformSection notSupported={["javacript.cordova", "javascript.capacitor", "javascript.electron"]}>
23+
24+
<Alert title="Deprecation Notice">
25+
26+
{/* 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. */}
27+
28+
Starting with SDK version 8.43.0 and up, the `autoSessionTracking` option has been deprecated. You can use the [BrowserSession integration](/platforms/javascript/configuration/integrations/browsersession/) in browser environments and the [Http integration](/platforms/javascript/guides/node/configuration/integrations/http/) (via the `trackIncomingRequestsAsSessions` option) in Node.js runtime.
29+
30+
</Alert>
31+
32+
</PlatformSection>

‎platform-includes/configuration/auto-session-tracking/javascript.node.mdx

Lines changed: 14 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -14,3 +14,17 @@ Sentry.init({
1414
autoSessionTracking: false, // default: true
1515
});
1616
```
17+
18+
{/* TODO(v9): Remove this notice? */}
19+
20+
<PlatformSection notSupported={["javacript.cordova", "javascript.capacitor", "javascript.electron"]}>
21+
22+
<Alert title="Deprecation Notice">
23+
24+
{/* 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. */}
25+
26+
Starting with SDK version 8.43.0 and up, the `autoSessionTracking` option has been deprecated. You can use the [BrowserSession integration](/platforms/javascript/configuration/integrations/browsersession/) in browser environments and the [Http integration](/platforms/javascript/guides/node/configuration/integrations/http/) (via the `trackIncomingRequestsAsSessions` option) in Node.js runtime.
27+
28+
</Alert>
29+
30+
</PlatformSection>

‎platform-includes/configuration/integrations/javascript.astro.mdx

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -30,6 +30,7 @@ Depending on whether an integration enhances the functionality of a particular r
3030
| [`globalHandlersIntegration`](./globalhandlers) | ✓ | ✓ | | | |
3131
| [`httpContextIntegration`](./httpcontext) | ✓ | | | | ✓ |
3232
| [`browserProfilingIntegration`](./browserprofiling) | | | ✓ | | |
33+
| [`browserSessionIntegration`](./browsersession) | ✓ | | | | ✓ |
3334
| [`contextLinesIntegration`](./contextlines) | | ✓ | | | |
3435
| [`httpClientIntegration`](./httpclient) | | ✓ | | | |
3536
| [`moduleMetadataIntegration`](./modulemetadata) | | | | | ✓ |

‎platform-includes/configuration/integrations/javascript.gatsby.mdx

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -11,6 +11,7 @@
1111
| [`inboundFiltersIntegration`](./inboundfilters) | ✓ | ✓ | | | |
1212
| [`linkedErrorsIntegration`](./linkederrors) | ✓ | ✓ | | | |
1313
| [`browserProfilingIntegration`](./browserprofiling) | | | ✓ | | |
14+
| [`browserSessionIntegration`](./browsersession) | ✓ | | | | ✓ |
1415
| [`browserTracingIntegration`](./browsertracing) | | | ✓ | | ✓ |
1516
| [`captureConsoleIntegration`](./captureconsole) | | | | | ✓ |
1617
| [`contextLinesIntegration`](./contextlines) | | ✓ | | | |

‎platform-includes/configuration/integrations/javascript.mdx

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -11,6 +11,7 @@
1111
| [`inboundFiltersIntegration`](./inboundfilters) | ✓ | ✓ | | | |
1212
| [`linkedErrorsIntegration`](./linkederrors) | ✓ | ✓ | | | |
1313
| [`browserProfilingIntegration`](./browserprofiling) | | | ✓ | | |
14+
| [`browserSessionIntegration`](./browsersession) | ✓ | | | | ✓ |
1415
| [`browserTracingIntegration`](./browsertracing) | | | ✓ | | ✓ |
1516
| [`captureConsoleIntegration`](./captureconsole) | | | | | ✓ |
1617
| [`contextLinesIntegration`](./contextlines) | | ✓ | | | |

‎platform-includes/configuration/integrations/javascript.nextjs.mdx

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -31,6 +31,7 @@ Depending on whether an integration enhances the functionality of a particular r
3131
| [`globalHandlersIntegration`](./globalhandlers) | ✓ | ✓ | | | |
3232
| [`httpContextIntegration`](./httpcontext) | ✓ | | | | ✓ |
3333
| [`browserProfilingIntegration`](./browserprofiling) | | | ✓ | | |
34+
| [`browserSessionIntegration`](./browsersession) | ✓ | | | | ✓ |
3435
| [`contextLinesIntegration`](./contextlines) | | ✓ | | | |
3536
| [`httpClientIntegration`](./httpclient) | | ✓ | | | |
3637
| [`moduleMetadataIntegration`](./modulemetadata) | | | | | ✓ |

‎platform-includes/configuration/integrations/javascript.nuxt.mdx

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -30,6 +30,7 @@ Depending on whether an integration enhances the functionality of a particular r
3030
| [`globalHandlersIntegration`](./globalhandlers) | ✓ | ✓ | | | |
3131
| [`httpContextIntegration`](./httpcontext) | ✓ | | | | ✓ |
3232
| [`browserProfilingIntegration`](./browserprofiling) | | | ✓ | | |
33+
| [`browserSessionIntegration`](./browsersession) | ✓ | | | | ✓ |
3334
| [`contextLinesIntegration`](./contextlines) | | ✓ | | | |
3435
| [`httpClientIntegration`](./httpclient) | | ✓ | | | |
3536
| [`moduleMetadataIntegration`](./modulemetadata) | | | | | ✓ |

‎platform-includes/configuration/integrations/javascript.remix.mdx

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -30,6 +30,7 @@ Depending on whether an integration enhances the functionality of a particular r
3030
| [`globalHandlersIntegration`](./globalhandlers) | ✓ | ✓ | | | |
3131
| [`httpContextIntegration`](./httpcontext) | ✓ | | | | ✓ |
3232
| [`browserProfilingIntegration`](./browserprofiling) | | | ✓ | | |
33+
| [`browserSessionIntegration`](./browsersession) | ✓ | | | | ✓ |
3334
| [`contextLinesIntegration`](./contextlines) | | ✓ | | | |
3435
| [`httpClientIntegration`](./httpclient) | | ✓ | | | |
3536
| [`moduleMetadataIntegration`](./modulemetadata) | | | | | ✓ |

‎platform-includes/configuration/integrations/javascript.solidstart.mdx

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -30,6 +30,7 @@ Depending on whether an integration enhances the functionality of a particular r
3030
| [`globalHandlersIntegration`](./globalhandlers) | ✓ | ✓ | | | |
3131
| [`httpContextIntegration`](./httpcontext) | ✓ | | | | ✓ |
3232
| [`browserProfilingIntegration`](./browserprofiling) | | | ✓ | | |
33+
| [`browserSessionIntegration`](./browsersession) | ✓ | | | | ✓ |
3334
| [`contextLinesIntegration`](./contextlines) | | ✓ | | | |
3435
| [`httpClientIntegration`](./httpclient) | | ✓ | | | |
3536
| [`moduleMetadataIntegration`](./modulemetadata) | | | | | ✓ |

‎platform-includes/configuration/integrations/javascript.sveltekit.mdx

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -30,6 +30,7 @@ Depending on whether an integration enhances the functionality of a particular r
3030
| [`globalHandlersIntegration`](./globalhandlers) | ✓ | ✓ | | | |
3131
| [`httpContextIntegration`](./httpcontext) | ✓ | | | | ✓ |
3232
| [`browserProfilingIntegration`](./browserprofiling) | | | ✓ | | |
33+
| [`browserSessionIntegration`](./browsersession) | ✓ | | | | ✓ |
3334
| [`contextLinesIntegration`](./contextlines) | | ✓ | | | |
3435
| [`httpClientIntegration`](./httpclient) | | ✓ | | | |
3536
| [`moduleMetadataIntegration`](./modulemetadata) | | | | | ✓ |

0 commit comments

Comments
 (0)