feat(core): Allow to pass mechanism as event hint (#9590)

This allows to pass `mechanism` as an event hint. Also, we now allow to
pass `hint` as an alternative to `CaptureContext` to `captureException`
as second argument.

We have quite a lot of code where we fork a scope and add an event
processor, only to add a mechanism to the event.
Since this is a quite common pattern, I figured it makes more sense to
allow to pass a mechanism as an EventHint.

In addition, I noticed that while `hub.captureException()` takes an
event hint as second argument, in the core exported `captureException()`
we take a `CaptureContext` as second argument instead (for legacy
reasons).

In order to be able to pass a mechanism there as well, I updated the
method signature to allow _either_ a CaptureContext _or_ an EventHint. I
wrote some tests covering this to make sure that works - it's a bit
tricky since both can be POJOs, but no fields overlap so we are able to
parse this together.

Author: mydea

packages/angular/src/errorhandler.ts

@@ -2,8 +2,8 @@ import { HttpErrorResponse } from '@angular/common/http';
 import type { ErrorHandler as AngularErrorHandler } from '@angular/core';
 import { Inject, Injectable } from '@angular/core';
 import * as Sentry from '@sentry/browser';
-import type { Event, Scope } from '@sentry/types';
-import { addExceptionMechanism, isString } from '@sentry/utils';
+import type { Event } from '@sentry/types';
+import { isString } from '@sentry/utils';
 
 import { runOutsideAngular } from './zone';
 
@@ -102,17 +102,8 @@ class SentryErrorHandler implements AngularErrorHandler {
 
     // Capture handled exception and send it to Sentry.
     const eventId = runOutsideAngular(() =>
-      Sentry.captureException(extractedError, (scope: Scope) => {
-        scope.addEventProcessor(event => {
-          addExceptionMechanism(event, {
-            type: 'angular',
-            handled: false,
-          });
-
-          return event;
-        });
-
-        return scope;
+      Sentry.captureException(extractedError, {
+        mechanism: { type: 'angular', handled: false },
       }),
     );
 

packages/angular/test/errorhandler.test.ts

@@ -1,6 +1,6 @@
 import { captureException, configureScope, getCurrentHub, startSpan } from '@sentry/node';
 import type { Hub, Span } from '@sentry/types';
-import { addExceptionMechanism, objectify, stripUrlQueryAndFragment, tracingContextFromHeaders } from '@sentry/utils';
+import { objectify, stripUrlQueryAndFragment, tracingContextFromHeaders } from '@sentry/utils';
 import type { APIContext, MiddlewareResponseHandler } from 'astro';
 
 import { getTracingMetaTags } from './meta';
@@ -34,19 +34,14 @@ function sendErrorToSentry(e: unknown): unknown {
   // store a seen flag on it.
   const objectifiedErr = objectify(e);
 
-  captureException(objectifiedErr, scope => {
-    scope.addEventProcessor(event => {
-      addExceptionMechanism(event, {
-        type: 'astro',
-        handled: false,
-        data: {
-          function: 'astroMiddleware',
-        },
-      });
-      return event;
-    });
-
-    return scope;
+  captureException(objectifiedErr, {
+    mechanism: {
+      type: 'astro',
+      handled: false,
+      data: {
+        function: 'astroMiddleware',
+      },
+    },
   });
 
   return objectifiedErr;

packages/astro/src/server/middleware.ts

@@ -1,5 +1,4 @@
 import * as SentryNode from '@sentry/node';
-import * as SentryUtils from '@sentry/utils';
 import { vi } from 'vitest';
 
 import { handleRequest, interpolateRouteFromUrlAndParams } from '../../src/server/middleware';
@@ -59,12 +58,7 @@ describe('sentryMiddleware', () => {
   });
 
   it('throws and sends an error to sentry if `next()` throws', async () => {
-    const scope = {
-      addEventProcessor: vi.fn().mockImplementation(cb => cb({})),
-    };
-    // @ts-expect-error, just testing the callback, this is okay for this test
-    const captureExceptionSpy = vi.spyOn(SentryNode, 'captureException').mockImplementation((ex, cb) => cb(scope));
-    const addExMechanismSpy = vi.spyOn(SentryUtils, 'addExceptionMechanism');
+    const captureExceptionSpy = vi.spyOn(SentryNode, 'captureException');
 
     const middleware = handleRequest();
     const ctx = {
@@ -86,16 +80,9 @@ describe('sentryMiddleware', () => {
     // @ts-expect-error, a partial ctx object is fine here
     await expect(async () => middleware(ctx, next)).rejects.toThrowError();
 
-    expect(captureExceptionSpy).toHaveBeenCalledWith(error, expect.any(Function));
-    expect(scope.addEventProcessor).toHaveBeenCalledTimes(1);
-    expect(addExMechanismSpy).toHaveBeenCalledWith(
-      {}, // the mocked event
-      {
-        handled: false,
-        type: 'astro',
-        data: { function: 'astroMiddleware' },
-      },
-    );
+    expect(captureExceptionSpy).toHaveBeenCalledWith(error, {
+      mechanism: { handled: false, type: 'astro', data: { function: 'astroMiddleware' } },
+    });
   });
 
   it('attaches tracing headers', async () => {

packages/astro/test/server/middleware.test.ts

@@ -1,5 +1,5 @@
 import { captureException, withScope } from '@sentry/core';
-import type { DsnLike, Event as SentryEvent, Mechanism, Scope, WrappedFunction } from '@sentry/types';
+import type { DsnLike, Mechanism, WrappedFunction } from '@sentry/types';
 import {
   addExceptionMechanism,
   addExceptionTypeValue,
@@ -99,8 +99,8 @@ export function wrap(
     } catch (ex) {
       ignoreNextOnError();
 
-      withScope((scope: Scope) => {
-        scope.addEventProcessor((event: SentryEvent) => {
+      withScope(scope => {
+        scope.addEventProcessor(event => {
           if (options.mechanism) {
             addExceptionTypeValue(event, undefined, undefined);
             addExceptionMechanism(event, options.mechanism);

packages/browser/src/helpers.ts

@@ -1,15 +1,7 @@
 /* eslint-disable @typescript-eslint/no-unsafe-member-access */
 import { getCurrentHub } from '@sentry/core';
-import type { Event, EventHint, Hub, Integration, Primitive, StackParser } from '@sentry/types';
-import {
-  addExceptionMechanism,
-  addInstrumentationHandler,
-  getLocationHref,
-  isErrorEvent,
-  isPrimitive,
-  isString,
-  logger,
-} from '@sentry/utils';
+import type { Event, Hub, Integration, Primitive, StackParser } from '@sentry/types';
+import { addInstrumentationHandler, getLocationHref, isErrorEvent, isPrimitive, isString, logger } from '@sentry/utils';
 
 import type { BrowserClient } from '../client';
 import { eventFromUnknownInput } from '../eventbuilder';
@@ -103,7 +95,13 @@ function _installGlobalOnErrorHandler(): void {
 
       event.level = 'error';
 
-      addMechanismAndCapture(hub, error, event, 'onerror');
+      hub.captureEvent(event, {
+        originalException: error,
+        mechanism: {
+          handled: false,
+          type: 'onerror',
+        },
+      });
     },
   );
 }
@@ -149,7 +147,14 @@ function _installGlobalOnUnhandledRejectionHandler(): void {
 
       event.level = 'error';
 
-      addMechanismAndCapture(hub, error, event, 'onunhandledrejection');
+      hub.captureEvent(event, {
+        originalException: error,
+        mechanism: {
+          handled: false,
+          type: 'onunhandledrejection',
+        },
+      });
+
       return;
     },
   );
@@ -243,16 +248,6 @@ function globalHandlerLog(type: string): void {
   __DEBUG_BUILD__ && logger.log(`Global Handler attached: ${type}`);
 }
 
-function addMechanismAndCapture(hub: Hub, error: EventHint['originalException'], event: Event, type: string): void {
-  addExceptionMechanism(event, {
-    handled: false,
-    type,
-  });
-  hub.captureEvent(event, {
-    originalException: error,
-  });
-}
-
 function getHubAndOptions(): [Hub, StackParser, boolean | undefined] {
   const hub = getCurrentHub();
   const client = hub.getClient<BrowserClient>();

packages/browser/src/integrations/globalhandlers.ts

@@ -1,25 +1,6 @@
 import { captureException, continueTrace, runWithAsyncContext, startSpan, Transaction } from '@sentry/core';
 import type { Integration } from '@sentry/types';
-import { addExceptionMechanism, getSanitizedUrlString, parseUrl } from '@sentry/utils';
-
-function sendErrorToSentry(e: unknown): unknown {
-  captureException(e, scope => {
-    scope.addEventProcessor(event => {
-      addExceptionMechanism(event, {
-        type: 'bun',
-        handled: false,
-        data: {
-          function: 'serve',
-        },
-      });
-      return event;
-    });
-
-    return scope;
-  });
-
-  return e;
-}
+import { getSanitizedUrlString, parseUrl } from '@sentry/utils';
 
 /**
  * Instruments `Bun.serve` to automatically create transactions and capture errors.
@@ -115,7 +96,15 @@ function instrumentBunServeOptions(serveOptions: Parameters<typeof Bun.serve>[0]
                   }
                   return response;
                 } catch (e) {
-                  sendErrorToSentry(e);
+                  captureException(e, {
+                    mechanism: {
+                      type: 'bun',
+                      handled: false,
+                      data: {
+                        function: 'serve',
+                      },
+                    },
+                  });
                   throw e;
                 }
               },

packages/bun/src/integrations/bunserver.ts

@@ -20,6 +20,8 @@ import { isThenable, logger, timestampInSeconds, uuid4 } from '@sentry/utils';
 import type { Hub } from './hub';
 import { getCurrentHub } from './hub';
 import type { Scope } from './scope';
+import type { ExclusiveEventHintOrCaptureContext } from './utils/prepareEvent';
+import { parseEventHintOrCaptureContext } from './utils/prepareEvent';
 
 // Note: All functions in this file are typed with a return value of `ReturnType<Hub[HUB_FUNCTION]>`,
 // where HUB_FUNCTION is some method on the Hub class.
@@ -30,14 +32,15 @@ import type { Scope } from './scope';
 
 /**
  * Captures an exception event and sends it to Sentry.
- *
- * @param exception An exception-like object.
- * @param captureContext Additional scope data to apply to exception event.
- * @returns The generated eventId.
+ * This accepts an event hint as optional second parameter.
+ * Alternatively, you can also pass a CaptureContext directly as second parameter.
  */
-// eslint-disable-next-line @typescript-eslint/no-explicit-any, @typescript-eslint/explicit-module-boundary-types
-export function captureException(exception: any, captureContext?: CaptureContext): ReturnType<Hub['captureException']> {
-  return getCurrentHub().captureException(exception, { captureContext });
+export function captureException(
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
+  exception: any,
+  hint?: ExclusiveEventHintOrCaptureContext,
+): ReturnType<Hub['captureException']> {
+  return getCurrentHub().captureException(exception, parseEventHintOrCaptureContext(hint));
 }
 
 /**

packages/core/src/exports.ts

@@ -1,10 +1,37 @@
-import type { Client, ClientOptions, Event, EventHint, StackFrame, StackParser } from '@sentry/types';
-import { dateTimestampInSeconds, GLOBAL_OBJ, normalize, resolvedSyncPromise, truncate, uuid4 } from '@sentry/utils';
+import type {
+  CaptureContext,
+  Client,
+  ClientOptions,
+  Event,
+  EventHint,
+  Scope as ScopeInterface,
+  ScopeContext,
+  StackFrame,
+  StackParser,
+} from '@sentry/types';
+import {
+  addExceptionMechanism,
+  dateTimestampInSeconds,
+  GLOBAL_OBJ,
+  normalize,
+  resolvedSyncPromise,
+  truncate,
+  uuid4,
+} from '@sentry/utils';
 
 import { DEFAULT_ENVIRONMENT } from '../constants';
 import { getGlobalEventProcessors, notifyEventProcessors } from '../eventProcessors';
 import { Scope } from '../scope';
 
+/**
+ * This type makes sure that we get either a CaptureContext, OR an EventHint.
+ * It does not allow mixing them, which could lead to unexpected outcomes, e.g. this is disallowed:
+ * { user: { id: '123' }, mechanism: { handled: false } }
+ */
+export type ExclusiveEventHintOrCaptureContext =
+  | (CaptureContext & Partial<{ [key in keyof EventHint]: never }>)
+  | (EventHint & Partial<{ [key in keyof ScopeContext]: never }>);
+
 /**
  * Adds common information to events.
  *
@@ -52,6 +79,10 @@ export function prepareEvent(
     finalScope = Scope.clone(finalScope).update(hint.captureContext);
   }
 
+  if (hint.mechanism) {
+    addExceptionMechanism(prepared, hint.mechanism);
+  }
+
   // We prepare the result here with a resolved Event.
   let result = resolvedSyncPromise<Event | null>(prepared);
 
@@ -309,3 +340,50 @@ function normalizeEvent(event: Event | null, depth: number, maxBreadth: number):
 
   return normalized;
 }
+
+/**
+ * Parse either an `EventHint` directly, or convert a `CaptureContext` to an `EventHint`.
+ * This is used to allow to update method signatures that used to accept a `CaptureContext` but should now accept an `EventHint`.
+ */
+export function parseEventHintOrCaptureContext(
+  hint: ExclusiveEventHintOrCaptureContext | undefined,
+): EventHint | undefined {
+  if (!hint) {
+    return undefined;
+  }
+
+  // If you pass a Scope or `() => Scope` as CaptureContext, we just return this as captureContext
+  if (hintIsScopeOrFunction(hint)) {
+    return { captureContext: hint };
+  }
+
+  if (hintIsScopeContext(hint)) {
+    return {
+      captureContext: hint,
+    };
+  }
+
+  return hint;
+}
+
+function hintIsScopeOrFunction(
+  hint: CaptureContext | EventHint,
+): hint is ScopeInterface | ((scope: ScopeInterface) => ScopeInterface) {
+  return hint instanceof Scope || typeof hint === 'function';
+}
+
+type ScopeContextProperty = keyof ScopeContext;
+const captureContextKeys: readonly ScopeContextProperty[] = [
+  'user',
+  'level',
+  'extra',
+  'contexts',
+  'tags',
+  'fingerprint',
+  'requestSession',
+  'propagationContext',
+] as const;
+
+function hintIsScopeContext(hint: Partial<ScopeContext> | EventHint): hint is Partial<ScopeContext> {
+  return Object.keys(hint).some(key => captureContextKeys.includes(key as ScopeContextProperty));
+}