docs(sessions): Add docs for unhandled session status #15086

ryan953 · 2025-09-30T17:01:43Z

DESCRIBE YOUR PR

Adding docs to describe the new Session status type: unhandled.

This status is only for Session data, not Issues!

We've basically taken the existing crashed status and split it into two parts:

A crashed session comes from an exception that was not handled by the application, and the language/framework did not handle it either resulting in a crash.
An unhandled session comes from an exception that was not handled by the application, but the language/framework does not allow the application to exit/crash/terminate/etc.

SDK Maintainers

As SDKs adopt this new status they will probably want to update pages like https://docs.sentry.io/platforms/javascript/configuration/releases/ to include a note about the new status, and the version when it was first supported.

Regardless of the SDK version, self-serve users will need server v25.9.0 to support unhandled properly.

IS YOUR CHANGE URGENT?

Help us prioritize incoming PRs by letting us know when the change needs to go live.

Urgent deadline (GA date, etc.):
Other deadline:
None: Not urgent, can wait up to 1 week+

SLA

Teamwork makes the dream work, so please add a reviewer to your PRs.
Please give the docs team up to 1 week to review your PR unless you've added an urgent due date to it.
Thanks in advance for your help!

PRE-MERGE CHECKLIST

Make sure you've checked the following before merging your changes:

Checked Vercel preview for correctness, including links
PR was reviewed and approved by any necessary SMEs (subject matter experts)
PR was reviewed and approved by a member of the Sentry docs team

vercel · 2025-09-30T17:01:49Z

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Preview	Comments	Updated (UTC)
develop-docs	Ready	Preview	Comment	Sep 30, 2025 5:32pm
sentry-docs	Ready	Preview	Comment	Sep 30, 2025 5:32pm

codecov · 2025-09-30T17:13:39Z

Bundle Report

Changes will decrease total bundle size by 15 bytes (-0.0%) ⬇️. This is within the configured threshold ✅

Detailed changes

Bundle name	Size	Change
sentry-docs-client-array-push	10.13MB	-6 bytes (-0.0%) ⬇️
sentry-docs-server-cjs	12.9MB	-9 bytes (-0.0%) ⬇️

Affected Assets, Files, and Routes:

view changes for bundle: sentry-docs-client-array-push

Assets Changed:

Asset Name	Size Change	Total Size	Change (%)
`static/chunks/pages/_app-*.js`	-3 bytes	882.71kB	-0.0%
`static/chunks/8321-*.js`	-3 bytes	425.87kB	-0.0%
`static/1ypuHrdhNystABxFfgeX5/_buildManifest.js` (New)	684 bytes	684 bytes	100.0% 🚀
`static/1ypuHrdhNystABxFfgeX5/_ssgManifest.js` (New)	77 bytes	77 bytes	100.0% 🚀
~~`static/sqlxXs5DR398tL4XU7efp/_buildManifest.js`~~ (Deleted)	-684 bytes	0 bytes	-100.0% 🗑️
~~`static/sqlxXs5DR398tL4XU7efp/_ssgManifest.js`~~ (Deleted)	-77 bytes	0 bytes	-100.0% 🗑️

view changes for bundle: sentry-docs-server-cjs

Assets Changed:

Asset Name	Size Change	Total Size	Change (%)
`1729.js`	-3 bytes	1.78MB	-0.0%
`../instrumentation.js`	-3 bytes	1.1MB	-0.0%
`9523.js`	-3 bytes	1.08MB	-0.0%

michellewzhang · 2025-09-30T23:07:38Z

develop-docs/sdk/telemetry/sessions/index.mdx

-  - a complete crash of the application occurred (crash to desktop, termination)
-  - a user feedback dialog is surfaced to the user. After this, the SDK must start a new session as if it fully crashed.;
+  - a complete crash of the application occurred (crash to desktop, termination).
+  - a user feedback dialog is surfaced to the user. After this, the SDK must start a new session as if it fully crashed.


Suggested change

- a user feedback dialog is surfaced to the user. After this, the SDK must start a new session as if it fully crashed.

- a crash report user feedback dialog is surfaced to the user. After this, the SDK must start a new session as if it fully crashed.

is this specific to sentry's dialog?

michellewzhang · 2025-09-30T23:08:21Z

develop-docs/sdk/telemetry/sessions/index.mdx

-### Crashed, Abnormal vs Errored
+### Crashed, Unhandled, Abnormal vs Errored
+
+A session is supposed to transition to `crashed` when it encountered an a full 


Suggested change

A session is supposed to transition to `crashed` when it encountered an a full

A session is supposed to transition to `crashed` when it encountered a full

Suggested change

A session is supposed to transition to `crashed` when it encountered an a full

A session is supposed to transition to `crashed` when it encounters a full

michellewzhang · 2025-09-30T23:09:37Z

develop-docs/sdk/telemetry/sessions/index.mdx

-the user encountered an error dialog. For server environments where we create sessions
-for every incoming request, `crashed` is basically like status code `500` internal server error.
-So if there is an unhandled error happening during the request, the session should be `crashed`.
+Note that `unhandled` became supported on the server in v25.9.0, prior to that


Suggested change

Note that `unhandled` became supported on the server in v25.9.0, prior to that

Note that `unhandled` became supported on the server in v25.9.0. Prior to that,

michellewzhang · 2025-09-30T23:09:51Z

develop-docs/sdk/telemetry/sessions/index.mdx


-Abnormal are sessions of which their fate is unknown. For desktop applications, for instance, it makes sense to transition a session to abnormal if it was stored
-but the exit of the application was not observed but also did not crash. These are situations where the user forced the app to close via the
+`abnormal` are sessions of which their fate is unknown. For desktop


Suggested change

`abnormal` are sessions of which their fate is unknown. For desktop

`abnormal` are sessions where their fate is unknown. For desktop

michellewzhang · 2025-09-30T23:10:09Z

develop-docs/sdk/telemetry/sessions/index.mdx

-but the exit of the application was not observed but also did not crash. These are situations where the user forced the app to close via the
+`abnormal` are sessions of which their fate is unknown. For desktop
+applications, for instance, it makes sense to transition a session to `abnormal`
+if it was stored but the exit of the application was not observed but also did


Suggested change

if it was stored but the exit of the application was not observed but also did

if it was stored but application exit was not observed but also did

michellewzhang · 2025-09-30T23:11:10Z

docs/product/releases/health/index.mdx

 ![Sort By: Active Users dropdown](./img/release_active_users.png)

-## Crashes
+## Crashes & Unhandled


Suggested change

## Crashes & Unhandled

## Crashes & Unhandled Errors

maybe?

michellewzhang · 2025-09-30T23:11:28Z

docs/product/releases/health/index.mdx

+## Crashes & Unhandled

-A _crash_ is when the application had an explicit unhandled error or hard crash. You'll typically be able to view the corresponding issue that captures this event in [sentry.io](https://sentry.io), and errors that did not cause the end of the application should not be included. To search for crash events in **Discover** or on the **Issues** page, filter by `error.unhandled:true`.
+A _crash_ is when the application had a hard crash, while _unhandled_ is when an error that wasn't explicitly handled by the application. You'll typically be able to view the corresponding issue that captures this event in [sentry.io](https://sentry.io), and errors that did not cause the end of the application should not be included. To search for crash events in **Discover** or on the **Issues** page, filter by `error.unhandled:true`.


Suggested change

A _crash_ is when the application had a hard crash, while _unhandled_ is when an error that wasn't explicitly handled by the application. You'll typically be able to view the corresponding issue that captures this event in [sentry.io](https://sentry.io), and errors that did not cause the end of the application should not be included. To search for crash events in **Discover** or on the **Issues** page, filter by `error.unhandled:true`.

A _crash_ is when the application had a hard crash, while _unhandled_ is an error that wasn't explicitly handled by the application. You'll typically be able to view the corresponding issue that captured the crashed event in [sentry.io](https://sentry.io); errors that did not cause the end of the application should not be included. To search for crash events in **Discover** or on the **Issues** page, filter by `error.unhandled:true`.

this paragraph is a bit unclear now that unhandled was added

michellewzhang · 2025-09-30T23:12:55Z

docs/product/releases/health/index.mdx

-A _crash_ is when the application had an explicit unhandled error or hard crash. You'll typically be able to view the corresponding issue that captures this event in [sentry.io](https://sentry.io), and errors that did not cause the end of the application should not be included. To search for crash events in **Discover** or on the **Issues** page, filter by `error.unhandled:true`.
+A _crash_ is when the application had a hard crash, while _unhandled_ is when an error that wasn't explicitly handled by the application. You'll typically be able to view the corresponding issue that captures this event in [sentry.io](https://sentry.io), and errors that did not cause the end of the application should not be included. To search for crash events in **Discover** or on the **Issues** page, filter by `error.unhandled:true`.
+
+Starting with v25.9.0, Sentry differentiates between crashes and unhandled errors and both are counted separately. Check your SDK release notes and update to the latest version to support _unhandled_ session status.


Suggested change

Starting with v25.9.0, Sentry differentiates between crashes and unhandled errors and both are counted separately. Check your SDK release notes and update to the latest version to support _unhandled_ session status.

Starting with v25.9.0, Sentry differentiates between crashes and unhandled errors, and both are counted separately. Check your SDK release notes and update to the latest version to support _unhandled_ session status.

michellewzhang · 2025-09-30T23:14:23Z

docs/product/releases/health/index.mdx

+
+One common misconception is that session data is derived from issues, and that the numbers can be cross referenced. This is not the case.
+
+Session data is unconditionally sent from SDKs when the integration is enabled (it is enabled by default in most SDKs). This dataset tracks every session as it is started and ended, and includes only basic tags related to release and environment. In contrast, Issues are derived from error events, which are subject to [inbound filters](/concepts/data-management/filtering/) and [sampling](/platform-redirect/?next=/configuration/sampling/) and [quota](/pricing/quotas/) limits.


Suggested change

Session data is unconditionally sent from SDKs when the integration is enabled (it is enabled by default in most SDKs). This dataset tracks every session as it is started and ended, and includes only basic tags related to release and environment. In contrast, Issues are derived from error events, which are subject to [inbound filters](/concepts/data-management/filtering/) and [sampling](/platform-redirect/?next=/configuration/sampling/) and [quota](/pricing/quotas/) limits.

Session data is unconditionally sent from SDKs when the integration is enabled (it is enabled by default in most SDKs). This dataset tracks every session start and end, and includes only basic tags related to release and environment. In contrast, issues are derived from error events, which are subject to [inbound filters](/concepts/data-management/filtering/), [sampling](/platform-redirect/?next=/configuration/sampling/), and [quota](/pricing/quotas/) limits.

michellewzhang · 2025-09-30T23:15:17Z

docs/product/releases/health/index.mdx


+### Unhandled
+
+The application had an explicit error that was not explicitly [unhandled](#crashes--unhandled). The language or framework prevented the process from terminating.


should it say "handled"?

coolguyzone · 2025-10-02T21:51:54Z

develop-docs/sdk/telemetry/sessions/index.mdx

  sessions ending in `exited` will be considered for session durations.
  A session is allowed to go to `exited` even if errors occurred.

+- `unhandled`: a session should be reported as unhandled under the following cases:


Suggested change

- `unhandled`: a session should be reported as unhandled under the following cases:

- `unhandled`: a session should be reported as unhandled in the following cases:

coolguyzone · 2025-10-02T21:56:05Z

develop-docs/sdk/telemetry/sessions/index.mdx

+It's acceptable to transition to the `crashed` state if the user encountered an
+error dialog.
+For server environments where we create sessions for every incoming request,
+`unhandled` is basically like status code `500` internal server error.


Suggested change

`unhandled` is basically like status code `500` internal server error.

`unhandled` is basically like status code `500 Internal Server Error`.

docs(sessions): Add docs for unhandled session status

a7b033a

codeowner-assignment bot requested review from a team September 30, 2025 17:02

vercel bot deployed to Preview – develop-docs September 30, 2025 17:06 View deployment

ryan953 requested review from a team September 30, 2025 17:07

vercel bot deployed to Preview – sentry-docs September 30, 2025 17:32 View deployment

michellewzhang reviewed Sep 30, 2025

View reviewed changes

Lms24 mentioned this pull request Oct 1, 2025

Assign status unhandled instead of crashed to sessions in browser SDK getsentry/sentry-javascript#17842

Open

philipphofmann mentioned this pull request Oct 2, 2025

Sessions: Add unhandled session status getsentry/sentry-cocoa#6326

Open

coolguyzone reviewed Oct 2, 2025

View reviewed changes

coolguyzone approved these changes Oct 2, 2025

View reviewed changes

	- a user feedback dialog is surfaced to the user. After this, the SDK must start a new session as if it fully crashed.
	- a crash report user feedback dialog is surfaced to the user. After this, the SDK must start a new session as if it fully crashed.

	A session is supposed to transition to `crashed` when it encountered an a full
	A session is supposed to transition to `crashed` when it encountered a full

	Note that `unhandled` became supported on the server in v25.9.0, prior to that
	Note that `unhandled` became supported on the server in v25.9.0. Prior to that,

	`abnormal` are sessions of which their fate is unknown. For desktop
	`abnormal` are sessions where their fate is unknown. For desktop

	if it was stored but the exit of the application was not observed but also did
	if it was stored but application exit was not observed but also did

	Starting with v25.9.0, Sentry differentiates between crashes and unhandled errors and both are counted separately. Check your SDK release notes and update to the latest version to support _unhandled_ session status.
	Starting with v25.9.0, Sentry differentiates between crashes and unhandled errors, and both are counted separately. Check your SDK release notes and update to the latest version to support _unhandled_ session status.


		One common misconception is that session data is derived from issues, and that the numbers can be cross referenced. This is not the case.

		Session data is unconditionally sent from SDKs when the integration is enabled (it is enabled by default in most SDKs). This dataset tracks every session as it is started and ended, and includes only basic tags related to release and environment. In contrast, Issues are derived from error events, which are subject to [inbound filters](/concepts/data-management/filtering/) and [sampling](/platform-redirect/?next=/configuration/sampling/) and [quota](/pricing/quotas/) limits.


		### Unhandled

		The application had an explicit error that was not explicitly [unhandled](#crashes--unhandled). The language or framework prevented the process from terminating.

	- `unhandled`: a session should be reported as unhandled under the following cases:
	- `unhandled`: a session should be reported as unhandled in the following cases:

	`unhandled` is basically like status code `500` internal server error.
	`unhandled` is basically like status code `500 Internal Server Error`.

Uh oh!

docs(sessions): Add docs for unhandled session status #15086

Are you sure you want to change the base?

docs(sessions): Add docs for unhandled session status #15086

Uh oh!

Conversation

ryan953 commented Sep 30, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

DESCRIBE YOUR PR

SDK Maintainers

IS YOUR CHANGE URGENT?

SLA

PRE-MERGE CHECKLIST

Uh oh!

vercel bot commented Sep 30, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

codecov bot commented Sep 30, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Bundle Report

Affected Assets, Files, and Routes:

Assets Changed:

Assets Changed:

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

ryan953 commented Sep 30, 2025 •

edited

Loading

vercel bot commented Sep 30, 2025 •

edited

Loading

codecov bot commented Sep 30, 2025 •

edited

Loading