feat(browser)!: Send session status unhandled instead of crashed for unhandled errors

Author: msonnb

dev-packages/browser-integration-tests/suites/sessions/page-lifecycle/test.ts

@@ -99,7 +99,7 @@ sentryTest('Updates the session when an error is thrown', async ({ getLocalTestU
     ...initialSession,
     errors: 1,
     init: false,
-    status: 'crashed',
+    status: 'unhandled',
     timestamp: expect.any(String),
   });
 });

dev-packages/browser-integration-tests/suites/sessions/update-session/test.ts

@@ -19,7 +19,7 @@ sentryTest('should update session when an error is thrown.', async ({ getLocalTe
 
   expect(updatedSession.init).toBe(false);
   expect(updatedSession.errors).toBe(1);
-  expect(updatedSession.status).toBe('crashed');
+  expect(updatedSession.status).toBe('unhandled');
   expect(pageloadSession.sid).toBe(updatedSession.sid);
 });
 

packages/browser/src/client.ts

@@ -7,6 +7,7 @@ import type {
   Options as CoreOptions,
   ParameterizedString,
   Scope,
+  SessionStatus,
   SeverityLevel,
 } from '@sentry/core/browser';
 import { addAutoIpAddressToSession, applySdkMetadata, Client, getSDKSource } from '@sentry/core/browser';
@@ -157,6 +158,14 @@ export class BrowserClient extends Client<BrowserClientOptions> {
 
     return super._prepareEvent(event, hint, currentScope, isolationScope);
   }
+
+  /**
+   * @inheritDoc
+   */
+  protected _getUnhandledSessionStatus(): SessionStatus {
+    // Unhandled errors don't actually crash the browser, so we report `unhandled` rather than `crashed`.
+    return 'unhandled';
+  }
 }
 
 /** Exported only for tests. */

packages/browser/test/client.test.ts

@@ -2,6 +2,7 @@
  * @vitest-environment jsdom
  */
 
+import { getCurrentScope, makeSession, setCurrentClient } from '@sentry/core/browser';
 import { afterEach, describe, expect, it, vi } from 'vitest';
 import { applyDefaultOptions, BrowserClient } from '../src/client';
 import { WINDOW } from '../src/helpers';
@@ -49,6 +50,51 @@ describe('BrowserClient', () => {
     expect(flushOutcomesSpy).not.toHaveBeenCalled();
     expect(flushSpy).toHaveBeenCalledTimes(1);
   });
+
+  describe('session status on unhandled errors', () => {
+    afterEach(() => {
+      getCurrentScope().setSession(undefined);
+      getCurrentScope().setClient(undefined);
+    });
+
+    it('sets the session status to "unhandled" for an unhandled exception', () => {
+      client = new BrowserClient(getDefaultBrowserClientOptions());
+      setCurrentClient(client);
+
+      const session = makeSession();
+      getCurrentScope().setSession(session);
+
+      client.captureException(new Error('test'), { mechanism: { handled: false } });
+
+      expect(session.status).toBe('unhandled');
+      expect(session.errors).toBe(1);
+    });
+
+    it('sets the session status to "unhandled" for a fatal event', () => {
+      client = new BrowserClient(getDefaultBrowserClientOptions());
+      setCurrentClient(client);
+
+      const session = makeSession();
+      getCurrentScope().setSession(session);
+
+      client.captureEvent({ message: 'test', level: 'fatal' });
+
+      expect(session.status).toBe('unhandled');
+    });
+
+    it('keeps the session status "ok" for a handled exception', () => {
+      client = new BrowserClient(getDefaultBrowserClientOptions());
+      setCurrentClient(client);
+
+      const session = makeSession();
+      getCurrentScope().setSession(session);
+
+      client.captureException(new Error('test'));
+
+      expect(session.status).toBe('ok');
+      expect(session.errors).toBe(1);
+    });
+  });
 });
 
 describe('applyDefaultOptions', () => {

packages/core/src/client.ts

@@ -32,7 +32,7 @@ import type { ParameterizedString } from './types/parameterize';
 import type { ReplayEndEvent, ReplayStartEvent } from './types/replay';
 import type { RequestEventData } from './types/request';
 import type { SdkMetadata } from './types/sdkmetadata';
-import type { Session, SessionAggregates } from './types/session';
+import type { Session, SessionAggregates, SessionStatus } from './types/session';
 import type { SeverityLevel } from './types/severity';
 import type { Span, SpanAttributes, SpanContextData, SpanJSON, StreamedSpanJSON } from './types/span';
 import type { StartSpanOptions } from './types/startSpanOptions';
@@ -1280,13 +1280,23 @@ export abstract class Client<O extends ClientOptions = ClientOptions> {
 
     if (shouldUpdateAndSend) {
       updateSession(session, {
-        ...(crashed && { status: 'crashed' }),
+        ...(crashed && { status: this._getUnhandledSessionStatus() }),
         errors: session.errors || Number(errored || crashed),
       });
       this.captureSession(session);
     }
   }
 
+  /**
+   * The session status to set when an unhandled error terminates a session.
+   *
+   * Defaults to `'crashed'`. Browser SDKs override this to `'unhandled'` because unhandled errors
+   * don't actually crash the browser.
+   */
+  protected _getUnhandledSessionStatus(): SessionStatus {
+    return 'crashed';
+  }
+
   /**
    * Determine if the client is finished processing. Returns a promise because it will wait `timeout` ms before saying
    * "no" (resolving to `false`) in order to give the client a chance to potentially finish first.

packages/core/src/types/session.ts

@@ -30,7 +30,7 @@ export interface Session {
 
 export type SessionContext = Partial<Session>;
 
-export type SessionStatus = 'ok' | 'exited' | 'crashed' | 'abnormal';
+export type SessionStatus = 'ok' | 'exited' | 'crashed' | 'abnormal' | 'unhandled';
 
 /** JSDoc */
 export interface SessionAggregates {