From a7b033a9dc686eb4e6c6168a19321a4051c93526 Mon Sep 17 00:00:00 2001 From: Ryan Albrecht Date: Tue, 30 Sep 2025 10:01:28 -0700 Subject: [PATCH] docs(sessions): Add docs for unhandled session status --- develop-docs/sdk/telemetry/sessions/index.mdx | 42 ++++++++++++------- .../android/configuration/releases.mdx | 2 +- .../apple/common/configuration/releases.mdx | 2 +- .../guides/flutter/configuration/releases.mdx | 2 +- .../dotnet/common/configuration/releases.mdx | 2 +- .../godot/configuration/releases.mdx | 2 +- .../java/common/configuration/releases.mdx | 2 +- .../common/configuration/releases.mdx | 2 +- .../native/common/configuration/releases.mdx | 2 +- .../powershell/configuration/releases.mdx | 2 +- .../python/configuration/releases.mdx | 2 +- .../python/configuration/sessions.mdx | 2 +- .../react-native/configuration/releases.mdx | 2 +- .../ruby/common/configuration/releases.mdx | 2 +- .../rust/common/configuration/releases.mdx | 2 +- .../unity/configuration/releases.mdx | 2 +- .../unreal/configuration/releases.mdx | 2 +- docs/product/alerts/alert-types.mdx | 2 +- docs/product/releases/health/index.mdx | 22 ++++++++-- docs/product/releases/release-details.mdx | 4 +- 20 files changed, 64 insertions(+), 38 deletions(-) diff --git a/develop-docs/sdk/telemetry/sessions/index.mdx b/develop-docs/sdk/telemetry/sessions/index.mdx index 29698b79548a2b..bf9eedc513d717 100644 --- a/develop-docs/sdk/telemetry/sessions/index.mdx +++ b/develop-docs/sdk/telemetry/sessions/index.mdx @@ -134,6 +134,7 @@ it must not be updated anymore. - `ok`: The session is currently in progress but healthy. This can be the terminal state of a session. - `exited`: The session terminated normally. +- `unhandled`: The session terminated with an unhandled error. - `crashed`: The session terminated in a crash. - `abnormal`: The session encountered a non crash related abnormal exit. @@ -217,6 +218,7 @@ something like this: - `did`: _Optional_. The distinct user id of the group. - `exited`: _Optional_. The number of sessions with status `"exited"` _without_ any errors. - `abnormal`: _Optional_. The number of sessions with status `"abnormal"`. +- `unhandled`: _Optional_. The number of sessions with status `"unhandled"`. - `crashed`: _Optional_. The number of sessions with status `"crashed"`. - `errored`: _Optional_. The number of sessions with status `"exited"` that had a non-zero `errors` count. @@ -265,7 +267,7 @@ deduplicate the total session count as an optimization. If the initial ### Terminal Session States A session can exist in one of two states: in progress or terminated. A terminated -session must not receive further updates. `exited`, `crashed` and `abnormal` +session must not receive further updates. `exited`, `unhandled`, `crashed` and `abnormal` are all terminal states. When a session reaches this state the client must not report any more session updates or start a new session. @@ -276,33 +278,43 @@ SDKs are encouraged to distinguish between different ways of ending a session: 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: + + - an unhandled error occurred and there is a natural session end (eg: end of HTTP request). + - the application did not handle an error, but the language or framework prevented the process from terminating. + - `crashed`: a session should be reported as crashed under the following cases: - - an unhandled error occurred and there is a natural session end (eg: end of HTTP request) - - 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. - `abnormal`: SDKs are encouraged to always transition a session to `exited` or `crashed` if they can do so. For SDKs that are capable of always ending sessions, they should end a session in `abnormal` if they could not detect the application shutting down correctly. Examples for abnormal sessions: - - a computer was shut down / lost power - - the user force closed an application through `kill -9` or the task manager + - a computer was shut down / lost power. + - the user force closed an application through `kill -9` or the task manager. Abnormal session ends are normally to be recorded on application restart. -### Crashed, Abnormal vs Errored +### Crashed, Unhandled, Abnormal vs Errored + +A session is supposed to transition to `crashed` when it encountered an a full +application crash and the process terminated. For applications that cannot fully +crash, such as a website, `unhandled` is more appropriate. +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. -A session is supposed to transition to `crashed` when it encountered an unhandled -error such as a full application crash. For applications that cannot fully -crash such as a website, 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, `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 +`crashed` was used for all of the cases above. -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 +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 task manager, the machine lost power or other situations. A session can be _stored_ by persisting it to disk eagerly. This saved file can be detected on application restart to close the session as `abnormal`. diff --git a/docs/platforms/android/configuration/releases.mdx b/docs/platforms/android/configuration/releases.mdx index dec66de035fe20..d1a53bb4d20e7a 100644 --- a/docs/platforms/android/configuration/releases.mdx +++ b/docs/platforms/android/configuration/releases.mdx @@ -29,7 +29,7 @@ After configuring your SDK, you can install a repository integration or manually ## Release Health -Monitor the [health of releases](/product/releases/health/) by observing user adoption, usage of the application, percentage of [crashes](/product/releases/health/#crashes), and [session data](/product/releases/health/#sessions). Release health will provide insight into the impact of crashes and bugs as it relates to user experience, and reveal trends with each new issue through the [Release Details](/product/releases/release-details/) graphs and filters. +Monitor the [health of releases](/product/releases/health/) by observing user adoption, usage of the application, percentage of [crashes](/product/releases/health/#crashes--unhandled), and [session data](/product/releases/health/#sessions). Release health will provide insight into the impact of crashes and bugs as it relates to user experience, and reveal trends with each new issue through the [Release Details](/product/releases/release-details/) graphs and filters. In order to monitor release health, the SDK sends session data. diff --git a/docs/platforms/apple/common/configuration/releases.mdx b/docs/platforms/apple/common/configuration/releases.mdx index 8d102d13f33e7d..28ad9195869ad0 100644 --- a/docs/platforms/apple/common/configuration/releases.mdx +++ b/docs/platforms/apple/common/configuration/releases.mdx @@ -27,7 +27,7 @@ After configuring your SDK, you can install a repository integration or manually ## Release Health -Monitor the [health of releases](/product/releases/health/) by observing user adoption, usage of the application, percentage of [crashes](/product/releases/health/#crashes), and [session data](/product/releases/health/#sessions). Release health will provide insight into the impact of crashes and bugs as it relates to user experience, and reveal trends with each new issue through the [Release Details](/product/releases/release-details/) graphs and filters. +Monitor the [health of releases](/product/releases/health/) by observing user adoption, usage of the application, percentage of [crashes](/product/releases/health/#crashes--unhandled), and [session data](/product/releases/health/#sessions). Release health will provide insight into the impact of crashes and bugs as it relates to user experience, and reveal trends with each new issue through the [Release Details](/product/releases/release-details/) graphs and filters. diff --git a/docs/platforms/dart/guides/flutter/configuration/releases.mdx b/docs/platforms/dart/guides/flutter/configuration/releases.mdx index 8c49e8dfdd77f2..152472c02f50f4 100644 --- a/docs/platforms/dart/guides/flutter/configuration/releases.mdx +++ b/docs/platforms/dart/guides/flutter/configuration/releases.mdx @@ -27,7 +27,7 @@ After configuring your SDK, you can install a repository integration or manually ## Release Health -Monitor the [health of releases](/product/releases/health/) by observing user adoption, usage of the application, percentage of [crashes](/product/releases/health/#crashes), and [session data](/product/releases/health/#sessions). Release health will provide insight into the impact of crashes and bugs as it relates to user experience, and reveal trends with each new issue through the [Release Details](/product/releases/release-details/) graphs and filters. +Monitor the [health of releases](/product/releases/health/) by observing user adoption, usage of the application, percentage of [crashes](/product/releases/health/#crashes--unhandled), and [session data](/product/releases/health/#sessions). Release health will provide insight into the impact of crashes and bugs as it relates to user experience, and reveal trends with each new issue through the [Release Details](/product/releases/release-details/) graphs and filters. In order to monitor release health, the SDK sends session data. diff --git a/docs/platforms/dotnet/common/configuration/releases.mdx b/docs/platforms/dotnet/common/configuration/releases.mdx index 9b216705b17505..7f0d78f0a9ae8b 100644 --- a/docs/platforms/dotnet/common/configuration/releases.mdx +++ b/docs/platforms/dotnet/common/configuration/releases.mdx @@ -27,7 +27,7 @@ After configuring your SDK, you can install a repository integration or manually ## Release Health -Monitor the [health of releases](/product/releases/health/) by observing user adoption, usage of the application, percentage of [crashes](/product/releases/health/#crashes), and [session data](/product/releases/health/#sessions). Release health will provide insight into the impact of crashes and bugs as it relates to user experience, and reveal trends with each new issue through the [Release Details](/product/releases/release-details/) graphs and filters. +Monitor the [health of releases](/product/releases/health/) by observing user adoption, usage of the application, percentage of [crashes](/product/releases/health/#crashes--unhandled), and [session data](/product/releases/health/#sessions). Release health will provide insight into the impact of crashes and bugs as it relates to user experience, and reveal trends with each new issue through the [Release Details](/product/releases/release-details/) graphs and filters. In order to monitor release health, the SDK sends session data. diff --git a/docs/platforms/godot/configuration/releases.mdx b/docs/platforms/godot/configuration/releases.mdx index 58dd8a809fa2c5..3c9d38de400ba7 100644 --- a/docs/platforms/godot/configuration/releases.mdx +++ b/docs/platforms/godot/configuration/releases.mdx @@ -33,7 +33,7 @@ After configuring your SDK, you can install a repository integration or manually ## Release Health -Monitor the [health of releases](/product/releases/health/) by observing user adoption, usage of the application, percentage of [crashes](/product/releases/health/#crashes), and [session data](/product/releases/health/#sessions). Release health will provide insight into the impact of crashes and bugs as it relates to user experience, and reveal trends with each new issue through the [Release Details](/product/releases/release-details/) graphs and filters. +Monitor the [health of releases](/product/releases/health/) by observing user adoption, usage of the application, percentage of [crashes](/product/releases/health/#crashes--unhandled), and [session data](/product/releases/health/#sessions). Release health will provide insight into the impact of crashes and bugs as it relates to user experience, and reveal trends with each new issue through the [Release Details](/product/releases/release-details/) graphs and filters. In order to monitor release health, the SDK sends session data. diff --git a/docs/platforms/java/common/configuration/releases.mdx b/docs/platforms/java/common/configuration/releases.mdx index 6aa0c962ad9381..42a0ab56cc6da6 100644 --- a/docs/platforms/java/common/configuration/releases.mdx +++ b/docs/platforms/java/common/configuration/releases.mdx @@ -29,7 +29,7 @@ After configuring your SDK, you can install a repository integration or manually ## Release Health -Monitor the [health of releases](/product/releases/health/) by observing user adoption, usage of the application, percentage of [crashes](/product/releases/health/#crashes), and [session data](/product/releases/health/#sessions). Release health will provide insight into the impact of crashes and bugs as it relates to user experience, and reveal trends with each new issue through the [Release Details](/product/releases/release-details/) graphs and filters. +Monitor the [health of releases](/product/releases/health/) by observing user adoption, usage of the application, percentage of [crashes](/product/releases/health/#crashes--unhandled), and [session data](/product/releases/health/#sessions). Release health will provide insight into the impact of crashes and bugs as it relates to user experience, and reveal trends with each new issue through the [Release Details](/product/releases/release-details/) graphs and filters. In order to monitor release health, the SDK sends session data. diff --git a/docs/platforms/javascript/common/configuration/releases.mdx b/docs/platforms/javascript/common/configuration/releases.mdx index 9492c36b7262ca..3327032df02223 100644 --- a/docs/platforms/javascript/common/configuration/releases.mdx +++ b/docs/platforms/javascript/common/configuration/releases.mdx @@ -29,7 +29,7 @@ After configuring your SDK, you can install a repository integration or manually ## Release Health -Monitor the [health of releases](/product/releases/health/) by observing user adoption, usage of the application, percentage of [crashes](/product/releases/health/#crashes), and [session data](/product/releases/health/#sessions). Release health will provide insight into the impact of crashes and bugs as it relates to user experience, and reveal trends with each new issue through the [Release Details](/product/releases/release-details/) graphs and filters. +Monitor the [health of releases](/product/releases/health/) by observing user adoption, usage of the application, percentage of [crashes](/product/releases/health/#crashes--unhandled), and [session data](/product/releases/health/#sessions). Release health will provide insight into the impact of crashes and bugs as it relates to user experience, and reveal trends with each new issue through the [Release Details](/product/releases/release-details/) graphs and filters. In order to monitor release health, the SDK sends session data. diff --git a/docs/platforms/native/common/configuration/releases.mdx b/docs/platforms/native/common/configuration/releases.mdx index 8c49e8dfdd77f2..152472c02f50f4 100644 --- a/docs/platforms/native/common/configuration/releases.mdx +++ b/docs/platforms/native/common/configuration/releases.mdx @@ -27,7 +27,7 @@ After configuring your SDK, you can install a repository integration or manually ## Release Health -Monitor the [health of releases](/product/releases/health/) by observing user adoption, usage of the application, percentage of [crashes](/product/releases/health/#crashes), and [session data](/product/releases/health/#sessions). Release health will provide insight into the impact of crashes and bugs as it relates to user experience, and reveal trends with each new issue through the [Release Details](/product/releases/release-details/) graphs and filters. +Monitor the [health of releases](/product/releases/health/) by observing user adoption, usage of the application, percentage of [crashes](/product/releases/health/#crashes--unhandled), and [session data](/product/releases/health/#sessions). Release health will provide insight into the impact of crashes and bugs as it relates to user experience, and reveal trends with each new issue through the [Release Details](/product/releases/release-details/) graphs and filters. In order to monitor release health, the SDK sends session data. diff --git a/docs/platforms/powershell/configuration/releases.mdx b/docs/platforms/powershell/configuration/releases.mdx index 8c49e8dfdd77f2..152472c02f50f4 100644 --- a/docs/platforms/powershell/configuration/releases.mdx +++ b/docs/platforms/powershell/configuration/releases.mdx @@ -27,7 +27,7 @@ After configuring your SDK, you can install a repository integration or manually ## Release Health -Monitor the [health of releases](/product/releases/health/) by observing user adoption, usage of the application, percentage of [crashes](/product/releases/health/#crashes), and [session data](/product/releases/health/#sessions). Release health will provide insight into the impact of crashes and bugs as it relates to user experience, and reveal trends with each new issue through the [Release Details](/product/releases/release-details/) graphs and filters. +Monitor the [health of releases](/product/releases/health/) by observing user adoption, usage of the application, percentage of [crashes](/product/releases/health/#crashes--unhandled), and [session data](/product/releases/health/#sessions). Release health will provide insight into the impact of crashes and bugs as it relates to user experience, and reveal trends with each new issue through the [Release Details](/product/releases/release-details/) graphs and filters. In order to monitor release health, the SDK sends session data. diff --git a/docs/platforms/python/configuration/releases.mdx b/docs/platforms/python/configuration/releases.mdx index 98c0bc7d5a4832..24ba0afa3f72fc 100644 --- a/docs/platforms/python/configuration/releases.mdx +++ b/docs/platforms/python/configuration/releases.mdx @@ -46,6 +46,6 @@ After configuring your SDK, you can install a repository integration or manually ## Release Health -Monitor the [health of releases](/product/releases/health/) by observing user adoption, usage of the application, percentage of [crashes](/product/releases/health/#crashes), and [session data](/product/releases/health/#sessions). Release health will provide insight into the impact of crashes and bugs as it relates to user experience, and reveal trends with each new issue through the [Release Details](/product/releases/release-details/) graphs and filters. +Monitor the [health of releases](/product/releases/health/) by observing user adoption, usage of the application, percentage of [crashes](/product/releases/health/#crashes--unhandled), and [session data](/product/releases/health/#sessions). Release health will provide insight into the impact of crashes and bugs as it relates to user experience, and reveal trends with each new issue through the [Release Details](/product/releases/release-details/) graphs and filters. In order to monitor release health, the SDK sends sessions. diff --git a/docs/platforms/python/configuration/sessions.mdx b/docs/platforms/python/configuration/sessions.mdx index bab570ccc4e03e..2f71806a21a1a3 100644 --- a/docs/platforms/python/configuration/sessions.mdx +++ b/docs/platforms/python/configuration/sessions.mdx @@ -10,6 +10,6 @@ A session represents the interaction between the user and the application. Sessi ## Tracking Release Health With Sessions -Sessions are used to monitor the [health of releases](/product/releases/health/) by observing user adoption, usage of the application, percentage of [crashes](/product/releases/health/#crashes), and [session data](/product/releases/health/#sessions). Release health will provide insight into the impact of crashes and bugs as it relates to user experience, and reveal trends with each new issue through the [Release Details](/product/releases/release-details/) graphs and filters. +Sessions are used to monitor the [health of releases](/product/releases/health/) by observing user adoption, usage of the application, percentage of [crashes](/product/releases/health/#crashes--unhandled), and [session data](/product/releases/health/#sessions). Release health will provide insight into the impact of crashes and bugs as it relates to user experience, and reveal trends with each new issue through the [Release Details](/product/releases/release-details/) graphs and filters. In order to monitor release health, you need to set a release. diff --git a/docs/platforms/react-native/configuration/releases.mdx b/docs/platforms/react-native/configuration/releases.mdx index dec66de035fe20..d1a53bb4d20e7a 100644 --- a/docs/platforms/react-native/configuration/releases.mdx +++ b/docs/platforms/react-native/configuration/releases.mdx @@ -29,7 +29,7 @@ After configuring your SDK, you can install a repository integration or manually ## Release Health -Monitor the [health of releases](/product/releases/health/) by observing user adoption, usage of the application, percentage of [crashes](/product/releases/health/#crashes), and [session data](/product/releases/health/#sessions). Release health will provide insight into the impact of crashes and bugs as it relates to user experience, and reveal trends with each new issue through the [Release Details](/product/releases/release-details/) graphs and filters. +Monitor the [health of releases](/product/releases/health/) by observing user adoption, usage of the application, percentage of [crashes](/product/releases/health/#crashes--unhandled), and [session data](/product/releases/health/#sessions). Release health will provide insight into the impact of crashes and bugs as it relates to user experience, and reveal trends with each new issue through the [Release Details](/product/releases/release-details/) graphs and filters. In order to monitor release health, the SDK sends session data. diff --git a/docs/platforms/ruby/common/configuration/releases.mdx b/docs/platforms/ruby/common/configuration/releases.mdx index 8dcdfb54100992..f388fb06c9cf16 100644 --- a/docs/platforms/ruby/common/configuration/releases.mdx +++ b/docs/platforms/ruby/common/configuration/releases.mdx @@ -27,7 +27,7 @@ After configuring your SDK, you can install a repository integration or manually ## Release Health -Monitor the [health of releases](/product/releases/health/) by observing user adoption, usage of the application, percentage of [crashes](/product/releases/health/#crashes), and [session data](/product/releases/health/#sessions). Release health will provide insight into the impact of crashes and bugs as it relates to user experience, and reveal trends with each new issue through the [Release Details](/product/releases/release-details/) graphs and filters. +Monitor the [health of releases](/product/releases/health/) by observing user adoption, usage of the application, percentage of [crashes](/product/releases/health/#crashes--unhandled), and [session data](/product/releases/health/#sessions). Release health will provide insight into the impact of crashes and bugs as it relates to user experience, and reveal trends with each new issue through the [Release Details](/product/releases/release-details/) graphs and filters. In order to monitor release health, the SDK sends session data. diff --git a/docs/platforms/rust/common/configuration/releases.mdx b/docs/platforms/rust/common/configuration/releases.mdx index 7df4067795ec42..31ec60cf7cc740 100644 --- a/docs/platforms/rust/common/configuration/releases.mdx +++ b/docs/platforms/rust/common/configuration/releases.mdx @@ -27,7 +27,7 @@ After configuring your SDK, you can install a repository integration or manually ## Release Health -Monitor the [health of releases](/product/releases/health/) by observing user adoption, usage of the application, percentage of [crashes](/product/releases/health/#crashes), and [session data](/product/releases/health/#sessions). Release health will provide insight into the impact of crashes and bugs as it relates to user experience, and reveal trends with each new issue through the [Release Details](/product/releases/release-details/) graphs and filters. +Monitor the [health of releases](/product/releases/health/) by observing user adoption, usage of the application, percentage of [crashes](/product/releases/health/#crashes--unhandled), and [session data](/product/releases/health/#sessions). Release health will provide insight into the impact of crashes and bugs as it relates to user experience, and reveal trends with each new issue through the [Release Details](/product/releases/release-details/) graphs and filters. In order to monitor release health, the SDK sends session data. diff --git a/docs/platforms/unity/configuration/releases.mdx b/docs/platforms/unity/configuration/releases.mdx index 58dd8a809fa2c5..3c9d38de400ba7 100644 --- a/docs/platforms/unity/configuration/releases.mdx +++ b/docs/platforms/unity/configuration/releases.mdx @@ -33,7 +33,7 @@ After configuring your SDK, you can install a repository integration or manually ## Release Health -Monitor the [health of releases](/product/releases/health/) by observing user adoption, usage of the application, percentage of [crashes](/product/releases/health/#crashes), and [session data](/product/releases/health/#sessions). Release health will provide insight into the impact of crashes and bugs as it relates to user experience, and reveal trends with each new issue through the [Release Details](/product/releases/release-details/) graphs and filters. +Monitor the [health of releases](/product/releases/health/) by observing user adoption, usage of the application, percentage of [crashes](/product/releases/health/#crashes--unhandled), and [session data](/product/releases/health/#sessions). Release health will provide insight into the impact of crashes and bugs as it relates to user experience, and reveal trends with each new issue through the [Release Details](/product/releases/release-details/) graphs and filters. In order to monitor release health, the SDK sends session data. diff --git a/docs/platforms/unreal/configuration/releases.mdx b/docs/platforms/unreal/configuration/releases.mdx index bb645d88baf66c..760dc0986e51aa 100644 --- a/docs/platforms/unreal/configuration/releases.mdx +++ b/docs/platforms/unreal/configuration/releases.mdx @@ -33,7 +33,7 @@ After configuring your SDK, you can install a repository integration or manually ## Release Health -Monitor the [health of releases](/product/releases/health/) by observing user adoption, usage of the application, percentage of [crashes](/product/releases/health/#crashes), and [session data](/product/releases/health/#sessions). Release health will provide insight into the impact of crashes and bugs as they relate to user experience, and reveal trends with each new issue through the [Release Details](/product/releases/release-details/) graphs and filters. +Monitor the [health of releases](/product/releases/health/) by observing user adoption, usage of the application, percentage of [crashes](/product/releases/health/#crashes--unhandled), and [session data](/product/releases/health/#sessions). Release health will provide insight into the impact of crashes and bugs as they relate to user experience, and reveal trends with each new issue through the [Release Details](/product/releases/release-details/) graphs and filters. In order to monitor release health, the SDK sends session data. diff --git a/docs/product/alerts/alert-types.mdx b/docs/product/alerts/alert-types.mdx index 3be6c19780e28b..66a542805c7d06 100644 --- a/docs/product/alerts/alert-types.mdx +++ b/docs/product/alerts/alert-types.mdx @@ -60,7 +60,7 @@ Error alerts are useful for monitoring the overall level of errors in your proje ### Sessions (Crash Rate Alerts) -Crash rate alerts can give you a better picture of the health of your app on a per project basis or in a specific release. They trigger when the crash-free percentage for either [sessions or users](/product/releases/health/#active-sessionsusers) falls below a specific threshold. This could happen because of a spike in the number of session or user [crashes](/product/releases/health/#crashes). +Crash rate alerts can give you a better picture of the health of your app on a per project basis or in a specific release. They trigger when the crash-free percentage for either [sessions or users](/product/releases/health/#active-sessionsusers) falls below a specific threshold. This could happen because of a spike in the number of session or user [crashes](/product/releases/health/#crashes--unhandled). - **Crash Free Session Rate:** Alerts when the number of crashed sessions exceeds the threshold you set. A session begins when a user starts the application and ends when it’s closed or sent to the background. A crash is when a session ends due to an error. diff --git a/docs/product/releases/health/index.mdx b/docs/product/releases/health/index.mdx index 96a25646ef5148..d9547024107822 100644 --- a/docs/product/releases/health/index.mdx +++ b/docs/product/releases/health/index.mdx @@ -10,7 +10,7 @@ Note, that Sessions (as described below) are not the same as a [Session Replay]( -You can monitor the health of releases by observing user adoption, usage of your application, percentage of [crashes](#crashes), and [session data](#sessions). Release health data provides insight into the impact of crashes and bugs related to user experience and reveals trends with each new issue through the release details, graphs, and filters. This data is primarily displayed on the [Releases](/product/releases/) and [Release Details](/product/releases/release-details) pages, but is also reflected in other parts of [sentry.io](https://sentry.io). +You can monitor the health of releases by observing user adoption, usage of your application, percentage of [crashes](#crashes--unhandled), and [session data](#sessions). Release health data provides insight into the impact of crashes and bugs related to user experience and reveals trends with each new issue through the release details, graphs, and filters. This data is primarily displayed on the [Releases](/product/releases/) and [Release Details](/product/releases/release-details) pages, but is also reflected in other parts of [sentry.io](https://sentry.io). > Many SDKs automatically manage the start and end of [sessions](#sessions) when the SDK is initialized, but release health configuration is key to ensuring you're receiving useful data, so check out our information on [which SDKs support release health](/product/releases/setup/#release-health) for links to configuring the SDK, as needed. @@ -85,9 +85,11 @@ Depending on your "Display" selection, the sort options for the **Releases** pag ![Sort By: Active Users dropdown](./img/release_active_users.png) -## Crashes +## 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`. + +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. ### Crash Free Sessions/Users @@ -113,6 +115,14 @@ Please note that the number of crashes is not expected to match the number of cr The number of users that experienced a crash in the specified time range. +## Sessions vs. Issues + +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. + +These two systems work in parallel to provide different views of your application's health. Session data enables the Release Adoption and Release Health charts and views which show you the health of your application at a high level, with no sampling or filtering applied. Issues data enables you to drill down into specific issues and have all the context you need to fix it. + ## Release Adoption Depending on the selected display option, we show either: @@ -166,9 +176,13 @@ A session can have one of the following statuses: The application timed out, froze, or was forced to quit by the operating system. There is usually no corresponding Sentry issue, as this is a passive action. +### Unhandled + +The application had an explicit error that was not explicitly [unhandled](#crashes--unhandled). The language or framework prevented the process from terminating. + ### Crashed -The application had an explicit unhandled error or hard [crash](#crashes). +The application had a hard [crash](#crashes--unhandled). ### Errored diff --git a/docs/product/releases/release-details.mdx b/docs/product/releases/release-details.mdx index f72716e953223d..a95913a874cdfa 100644 --- a/docs/product/releases/release-details.mdx +++ b/docs/product/releases/release-details.mdx @@ -13,7 +13,7 @@ The **Release Details** page focuses on an individual release. Elements of the r The graph at the top of the page provides insights into the health of your release by allowing you to choose which metric it displays. Select the time range that you want to review (the default range is the entire release period) and choose from these metrics in the table below the graph: - [Crash Free Session Rate](/product/releases/health/#crash-free-sessionsusers) -- [Healthy](/product/releases/health/#healthy), [Abnormal](/product/releases/health/#abnormal), [Errored](/product/releases/health/#errored) session rate +- [Healthy](/product/releases/health/#healthy), [Abnormal](/product/releases/health/#abnormal), [Errored](/product/releases/health/#errored), [Unhandled](/product/releases/health/#unhandled) session rate - [Crash Free User Rate](/product/releases/health/#crash-free-sessionsusers) - Crashed Session Rate - [Crashed User Rate](/product/releases/health/#crashed-users) @@ -24,7 +24,7 @@ The graph at the top of the page provides insights into the health of your relea In the table below the graph, percentage-based metrics of this release are compared to the average of all releases, so you can spot any differences in trend. -[Errored](/product/releases/health/#errored) sessions are likely to result in handled issues, and [crashed](/product/releases/health/#crashes) sessions in unhandled issues. Click on the issues links to see them in the [Issues](/product/issues/) page. +[Errored](/product/releases/health/#errored) sessions are likely to result in handled issues, and [crashed](/product/releases/health/#crashes--unhandled) sessions in unhandled issues. Click on the issues links to see them in the [Issues](/product/issues/) page. Click on any option in the graph legend to hide it. For example, in a "Session Count" graph, you might hide "Healthy" sessions to see "Crashed" ones in better scale. In the image below, the healthy sessions are displayed, but there are so many healthy sessions compared to all other session types that the crashed ones become invisible in the graph: