feat(core): Add addEventProcessor method (#9554)

And deprecate `addGlobalEventProcessor()` and
`getGlobalEventProcessors()`.

In v8, all event processors will be on the client only, streamlining
this a bit and preventing global "pollution".

Closes #9082

MIGRATION.md

@@ -8,6 +8,14 @@ npx @sentry/migr8@latest
 
 This will let you select which updates to run, and automatically update your code. Make sure to still review all code changes!
 
+## Deprecate `addGlobalEventProcessor` in favor of `addEventProcessor`
+
+Instead of using `addGlobalEventProcessor`, you should use `addEventProcessor` which does not add the event processor globally, but to the current client.
+
+For the vast majority of cases, the behavior of these should be the same. Only in the case where you have multiple clients will this differ - but you'll likely want to add event processors per-client then anyhow, not globally.
+
+In v8, we will remove the global event processors overall, as that allows us to avoid keeping global state that is not necessary.
+
 ## Deprecate `extractTraceParentData` export from `@sentry/core` & downstream packages
 
 Instead, import this directly from `@sentry/utils`.

packages/astro/src/index.server.ts

@@ -8,7 +8,9 @@ import { handleRequest } from './server/middleware';
 
 // Hence, we export everything from the Node SDK explicitly:
 export {
+  // eslint-disable-next-line deprecation/deprecation
   addGlobalEventProcessor,
+  addEventProcessor,
   addBreadcrumb,
   captureException,
   captureEvent,

packages/browser/src/exports.ts

@@ -21,7 +21,9 @@ export type { BrowserOptions } from './client';
 export type { ReportDialogOptions } from './helpers';
 
 export {
+  // eslint-disable-next-line deprecation/deprecation
   addGlobalEventProcessor,
+  addEventProcessor,
   addBreadcrumb,
   addIntegration,
   captureException,

packages/browser/src/integrations/dedupe.ts

@@ -25,7 +25,7 @@ export class Dedupe implements Integration {
   }
 
   /** @inheritDoc */
-  public setupOnce(_addGlobaleventProcessor: unknown, _getCurrentHub: unknown): void {
+  public setupOnce(_addGlobalEventProcessor: unknown, _getCurrentHub: unknown): void {
     // noop
   }
 

packages/bun/src/index.ts

@@ -24,7 +24,9 @@ export type { TransactionNamingScheme } from '@sentry/node';
 export type { BunOptions } from './types';
 
 export {
+  // eslint-disable-next-line deprecation/deprecation
   addGlobalEventProcessor,
+  addEventProcessor,
   addBreadcrumb,
   addIntegration,
   captureException,

packages/core/src/baseclient.ts

@@ -46,6 +46,7 @@ import {
 import { getEnvelopeEndpointWithUrlEncodedAuth } from './api';
 import { DEBUG_BUILD } from './debug-build';
 import { createEventEnvelope, createSessionEnvelope } from './envelope';
+import { getCurrentHub } from './hub';
 import type { IntegrationIndex } from './integration';
 import { setupIntegration, setupIntegrations } from './integration';
 import type { Scope } from './scope';
@@ -834,3 +835,17 @@ function isErrorEvent(event: Event): event is ErrorEvent {
 function isTransactionEvent(event: Event): event is TransactionEvent {
   return event.type === 'transaction';
 }
+
+/**
+ * Add an event processor to the current client.
+ * This event processor will run for all events processed by this client.
+ */
+export function addEventProcessor(callback: EventProcessor): void {
+  const client = getCurrentHub().getClient();
+
+  if (!client || !client.addEventProcessor) {
+    return;
+  }
+
+  client.addEventProcessor(callback);
+}

packages/core/src/eventProcessors.ts

@@ -5,16 +5,18 @@ import { DEBUG_BUILD } from './debug-build';
 
 /**
  * Returns the global event processors.
+ * @deprecated Global event processors will be removed in v8.
  */
 export function getGlobalEventProcessors(): EventProcessor[] {
   return getGlobalSingleton<EventProcessor[]>('globalEventProcessors', () => []);
 }
 
 /**
  * Add a EventProcessor to be kept globally.
- * @param callback EventProcessor to add
+ * @deprecated Use `addEventProcessor` instead. Global event processors will be removed in v8.
  */
 export function addGlobalEventProcessor(callback: EventProcessor): void {
+  // eslint-disable-next-line deprecation/deprecation
   getGlobalEventProcessors().push(callback);
 }
 

packages/core/src/index.ts

@@ -41,9 +41,12 @@ export {
 export { makeSession, closeSession, updateSession } from './session';
 export { SessionFlusher } from './sessionflusher';
 export { Scope } from './scope';
-export { addGlobalEventProcessor } from './eventProcessors';
+export {
+  // eslint-disable-next-line deprecation/deprecation
+  addGlobalEventProcessor,
+} from './eventProcessors';
 export { getEnvelopeEndpointWithUrlEncodedAuth, getReportDialogEndpoint } from './api';
-export { BaseClient } from './baseclient';
+export { BaseClient, addEventProcessor } from './baseclient';
 export { ServerRuntimeClient } from './server-runtime-client';
 export { initAndBind } from './sdk';
 export { createTransport } from './transports/base';

packages/core/src/integration.ts

@@ -105,6 +105,7 @@ export function setupIntegration(client: Client, integration: Integration, integ
 
   // `setupOnce` is only called the first time
   if (installedIntegrations.indexOf(integration.name) === -1) {
+    // eslint-disable-next-line deprecation/deprecation
     integration.setupOnce(addGlobalEventProcessor, getCurrentHub);
     installedIntegrations.push(integration.name);
   }

packages/core/src/integrations/inboundfilters.ts

@@ -50,7 +50,7 @@ export class InboundFilters implements Integration {
   /**
    * @inheritDoc
    */
-  public setupOnce(_addGlobaleventProcessor: unknown, _getCurrentHub: unknown): void {
+  public setupOnce(_addGlobalEventProcessor: unknown, _getCurrentHub: unknown): void {
     // noop
   }
 

packages/core/src/scope.ts

@@ -523,7 +523,12 @@ export class Scope implements ScopeInterface {
 
     // TODO (v8): Update this order to be: Global > Client > Scope
     return notifyEventProcessors(
-      [...(additionalEventProcessors || []), ...getGlobalEventProcessors(), ...this._eventProcessors],
+      [
+        ...(additionalEventProcessors || []),
+        // eslint-disable-next-line deprecation/deprecation
+        ...getGlobalEventProcessors(),
+        ...this._eventProcessors,
+      ],
       event,
       hint,
     );

packages/core/src/utils/prepareEvent.ts

@@ -110,7 +110,15 @@ export function prepareEvent(
   } else {
     // Apply client & global event processors even if there is no scope
     // TODO (v8): Update the order to be Global > Client
-    result = notifyEventProcessors([...clientEventProcessors, ...getGlobalEventProcessors()], prepared, hint);
+    result = notifyEventProcessors(
+      [
+        ...clientEventProcessors,
+        // eslint-disable-next-line deprecation/deprecation
+        ...getGlobalEventProcessors(),
+      ],
+      prepared,
+      hint,
+    );
   }
 
   return result.then(evt => {

packages/deno/src/index.ts

@@ -23,7 +23,9 @@ export type { AddRequestDataToEventOptions } from '@sentry/utils';
 export type { DenoOptions } from './types';
 
 export {
+  // eslint-disable-next-line deprecation/deprecation
   addGlobalEventProcessor,
+  addEventProcessor,
   addBreadcrumb,
   captureException,
   captureEvent,

packages/e2e-tests/README.md

@@ -107,7 +107,7 @@ A standardized frontend test application has the following features:
   be done with an event processor:
 
   ```ts
-  Sentry.addGlobalEventProcessor(event => {
+  Sentry.addEventProcessor(event => {
     if (
       event.type === 'transaction' &&
       (event.contexts?.trace?.op === 'pageload' || event.contexts?.trace?.op === 'navigation')

packages/e2e-tests/test-applications/create-next-app/sentry.client.config.ts

@@ -16,7 +16,7 @@ Sentry.init({
   // that it will also get attached to your source maps
 });
 
-Sentry.addGlobalEventProcessor(event => {
+Sentry.addEventProcessor(event => {
   if (
     event.type === 'transaction' &&
     (event.contexts?.trace?.op === 'pageload' || event.contexts?.trace?.op === 'navigation')

packages/e2e-tests/test-applications/create-next-app/sentry.server.config.ts

@@ -23,7 +23,7 @@ Sentry.init({
   integrations: [new Sentry.Integrations.LocalVariables()],
 });
 
-Sentry.addGlobalEventProcessor(event => {
+Sentry.addEventProcessor(event => {
   global.transactionIds = global.transactionIds || [];
 
   if (event.type === 'transaction') {

packages/e2e-tests/test-applications/create-remix-app-v2/app/entry.client.tsx

@@ -24,7 +24,7 @@ Sentry.init({
   replaysOnErrorSampleRate: 1.0, // If you're not already sampling the entire session, change the sample rate to 100% when sampling sessions where errors occur.
 });
 
-Sentry.addGlobalEventProcessor(event => {
+Sentry.addEventProcessor(event => {
   if (
     event.type === 'transaction' &&
     (event.contexts?.trace?.op === 'pageload' || event.contexts?.trace?.op === 'navigation')

packages/e2e-tests/test-applications/create-remix-app/app/entry.client.tsx

@@ -24,7 +24,7 @@ Sentry.init({
   replaysOnErrorSampleRate: 1.0, // If you're not already sampling the entire session, change the sample rate to 100% when sampling sessions where errors occur.
 });
 
-Sentry.addGlobalEventProcessor(event => {
+Sentry.addEventProcessor(event => {
   if (
     event.type === 'transaction' &&
     (event.contexts?.trace?.op === 'pageload' || event.contexts?.trace?.op === 'navigation')

packages/e2e-tests/test-applications/node-express-app/src/app.ts

@@ -89,7 +89,7 @@ app.listen(port, () => {
   console.log(`Example app listening on port ${port}`);
 });
 
-Sentry.addGlobalEventProcessor(event => {
+Sentry.addEventProcessor(event => {
   global.transactionIds = global.transactionIds || [];
 
   if (event.type === 'transaction') {

packages/e2e-tests/test-applications/react-create-hash-router/src/index.tsx

@@ -47,7 +47,7 @@ Object.defineProperty(window, 'sentryReplayId', {
   },
 });
 
-Sentry.addGlobalEventProcessor(event => {
+Sentry.addEventProcessor(event => {
   if (
     event.type === 'transaction' &&
     (event.contexts?.trace?.op === 'pageload' || event.contexts?.trace?.op === 'navigation')

packages/e2e-tests/test-applications/react-router-6-use-routes/src/index.tsx

@@ -45,7 +45,7 @@ Object.defineProperty(window, 'sentryReplayId', {
   },
 });
 
-Sentry.addGlobalEventProcessor(event => {
+Sentry.addEventProcessor(event => {
   if (
     event.type === 'transaction' &&
     (event.contexts?.trace?.op === 'pageload' || event.contexts?.trace?.op === 'navigation')

packages/e2e-tests/test-applications/standard-frontend-react-tracing-import/src/index.tsx

@@ -34,7 +34,7 @@ Sentry.init({
   release: 'e2e-test',
 });
 
-Sentry.addGlobalEventProcessor(event => {
+Sentry.addEventProcessor(event => {
   if (
     event.type === 'transaction' &&
     (event.contexts?.trace?.op === 'pageload' || event.contexts?.trace?.op === 'navigation')

packages/e2e-tests/test-applications/standard-frontend-react/src/index.tsx

@@ -46,7 +46,7 @@ Object.defineProperty(window, 'sentryReplayId', {
   },
 });
 
-Sentry.addGlobalEventProcessor(event => {
+Sentry.addEventProcessor(event => {
   if (
     event.type === 'transaction' &&
     (event.contexts?.trace?.op === 'pageload' || event.contexts?.trace?.op === 'navigation')

packages/ember/tests/test-helper.ts

@@ -13,7 +13,7 @@ declare global {
   }
 }
 
-Sentry.addGlobalEventProcessor(event => {
+Sentry.addEventProcessor(event => {
   if (isTesting()) {
     if (!window._sentryTestEvents) {
       window._sentryTestEvents = [];

packages/hub/src/index.ts

@@ -46,7 +46,8 @@ export const getCurrentHub = getCurrentHubCore;
 /**
  * @deprecated This export has moved to @sentry/core. The @sentry/hub package will be removed in v8.
  */
-export const addGlobalEventProcessor = addGlobalEventProcessorCore;
+
+export const addGlobalEventProcessor = addGlobalEventProcessorCore; // eslint-disable-line deprecation/deprecation
 
 /**
  * @deprecated This export has moved to @sentry/core. The @sentry/hub package will be removed in v8.

packages/hub/test/scope.test.ts

@@ -644,6 +644,7 @@ describe('Scope', () => {
       const localScope = new Scope();
       localScope.setExtra('a', 'b');
 
+      // eslint-disable-next-line deprecation/deprecation
       addGlobalEventProcessor((processedEvent: Event) => {
         processedEvent.dist = '1';
         return processedEvent;

packages/integrations/src/contextlines.ts

@@ -44,7 +44,7 @@ export class ContextLines implements Integration {
   /**
    * @inheritDoc
    */
-  public setupOnce(_addGlobaleventProcessor: unknown, _getCurrentHub: unknown): void {
+  public setupOnce(_addGlobalEventProcessor: unknown, _getCurrentHub: unknown): void {
     // noop
   }
 

packages/integrations/src/dedupe.ts

@@ -25,7 +25,7 @@ export class Dedupe implements Integration {
   }
 
   /** @inheritDoc */
-  public setupOnce(_addGlobaleventProcessor: unknown, _getCurrentHub: unknown): void {
+  public setupOnce(_addGlobalEventProcessor: unknown, _getCurrentHub: unknown): void {
     // noop
   }
 

packages/integrations/src/extraerrordata.ts

@@ -38,7 +38,7 @@ export class ExtraErrorData implements Integration {
   /**
    * @inheritDoc
    */
-  public setupOnce(_addGlobaleventProcessor: unknown, _getCurrentHub: unknown): void {
+  public setupOnce(_addGlobalEventProcessor: unknown, _getCurrentHub: unknown): void {
     // noop
   }
 

packages/integrations/src/rewriteframes.ts

@@ -43,7 +43,7 @@ export class RewriteFrames implements Integration {
   /**
    * @inheritDoc
    */
-  public setupOnce(_addGlobaleventProcessor: unknown, _getCurrentHub: unknown): void {
+  public setupOnce(_addGlobalEventProcessor: unknown, _getCurrentHub: unknown): void {
     // noop
   }
 

packages/integrations/src/sessiontiming.ts

@@ -23,7 +23,7 @@ export class SessionTiming implements Integration {
   /**
    * @inheritDoc
    */
-  public setupOnce(_addGlobaleventProcessor: unknown, _getCurrentHub: unknown): void {
+  public setupOnce(_addGlobalEventProcessor: unknown, _getCurrentHub: unknown): void {
     // noop
   }
 

packages/integrations/src/transaction.ts

@@ -19,7 +19,7 @@ export class Transaction implements Integration {
   /**
    * @inheritDoc
    */
-  public setupOnce(_addGlobaleventProcessor: unknown, _getCurrentHub: unknown): void {
+  public setupOnce(_addGlobalEventProcessor: unknown, _getCurrentHub: unknown): void {
     // noop
   }
 

packages/node-experimental/src/index.ts

@@ -24,7 +24,9 @@ export {
   extractRequestData,
   deepReadDirSync,
   getModuleFromFilename,
+  // eslint-disable-next-line deprecation/deprecation
   addGlobalEventProcessor,
+  addEventProcessor,
   addBreadcrumb,
   captureException,
   captureEvent,

packages/node/src/anr/index.ts

@@ -3,7 +3,7 @@ import { getClient, makeSession, updateSession } from '@sentry/core';
 import type { Event, Session, StackFrame } from '@sentry/types';
 import { logger, watchdogTimer } from '@sentry/utils';
 
-import { addGlobalEventProcessor, captureEvent, flush, getCurrentHub } from '..';
+import { addEventProcessor, captureEvent, flush, getCurrentHub } from '..';
 import { captureStackTrace } from './debugger';
 
 const DEFAULT_INTERVAL = 50;
@@ -191,7 +191,7 @@ function handleChildProcess(options: Options): void {
     });
   }
 
-  addGlobalEventProcessor(event => {
+  addEventProcessor(event => {
     // Strip sdkProcessingMetadata from all child process events to remove trace info
     delete event.sdkProcessingMetadata;
     event.tags = {

packages/node/src/index.ts

@@ -23,7 +23,9 @@ export type { AddRequestDataToEventOptions, TransactionNamingScheme } from '@sen
 export type { NodeOptions } from './types';
 
 export {
+  // eslint-disable-next-line deprecation/deprecation
   addGlobalEventProcessor,
+  addEventProcessor,
   addBreadcrumb,
   addIntegration,
   captureException,

packages/opentelemetry-node/src/spanprocessor.ts

@@ -2,7 +2,7 @@ import type { Context } from '@opentelemetry/api';
 import { SpanKind, context, trace } from '@opentelemetry/api';
 import { suppressTracing } from '@opentelemetry/core';
 import type { Span as OtelSpan, SpanProcessor as OtelSpanProcessor } from '@opentelemetry/sdk-trace-base';
-import { Transaction, addGlobalEventProcessor, addTracingExtensions, getClient, getCurrentHub } from '@sentry/core';
+import { Transaction, addEventProcessor, addTracingExtensions, getClient, getCurrentHub } from '@sentry/core';
 import type { DynamicSamplingContext, Span as SentrySpan, TraceparentData, TransactionContext } from '@sentry/types';
 import { logger } from '@sentry/utils';
 
@@ -22,7 +22,7 @@ export class SentrySpanProcessor implements OtelSpanProcessor {
   public constructor() {
     addTracingExtensions();
 
-    addGlobalEventProcessor(event => {
+    addEventProcessor(event => {
       const otelSpan = trace && trace.getActiveSpan && (trace.getActiveSpan() as OtelSpan | undefined);
       if (!otelSpan) {
         return event;