feat(node): Expose functional integrations to replace classes

We'll need to adjust the http & undici options a bit to align with otel integrations, but we can do this in a follow up, otherwise this will become a bit unwieldly...

Author: mydea

packages/node/src/index.ts

@@ -122,22 +122,36 @@ import * as Handlers from './handlers';
 import * as NodeIntegrations from './integrations';
 import * as TracingIntegrations from './tracing/integrations';
 
-const INTEGRATIONS = {
+/** @deprecated Import the integration function directly, e.g. `inboundFiltersIntegration()` instead of `new Integrations.InboundFilter(). */
+export const Integrations = {
   // eslint-disable-next-line deprecation/deprecation
   ...CoreIntegrations,
   ...NodeIntegrations,
   ...TracingIntegrations,
 };
 
+export { consoleIntegration } from './integrations/console';
+export { onUncaughtExceptionIntegration } from './integrations/onuncaughtexception';
+export { onUnhandledRejectionIntegration } from './integrations/onunhandledrejection';
+export { modulesIntegration } from './integrations/modules';
+export { contextLinesIntegration } from './integrations/contextlines';
+export { nodeContextIntegration } from './integrations/context';
+export { localVariablesIntegration } from './integrations/local-variables';
+export { spotlightIntegration } from './integrations/spotlight';
+export { anrIntegration } from './integrations/anr';
+export { hapiIntegration } from './integrations/hapi';
+// eslint-disable-next-line deprecation/deprecation
+export { Undici, undiciIntegration } from './integrations/undici';
+// eslint-disable-next-line deprecation/deprecation
+export { Http, httpIntegration } from './integrations/http';
+
 // TODO(v8): Remove all of these exports. They were part of a hotfix #10339 where we produced wrong .d.ts files because we were packing packages inside the /build folder.
 export type { LocalVariablesIntegrationOptions } from './integrations/local-variables/common';
 export type { DebugSession } from './integrations/local-variables/local-variables-sync';
 export type { AnrIntegrationOptions } from './integrations/anr/common';
-export { Undici } from './integrations/undici';
-export { Http } from './integrations/http';
 // ---
 
-export { INTEGRATIONS as Integrations, Handlers };
+export { Handlers };
 
 export { hapiErrorPlugin } from './integrations/hapi';
 

packages/node/src/integrations/anr/index.ts

@@ -1,6 +1,6 @@
 // TODO (v8): This import can be removed once we only support Node with global URL
 import { URL } from 'url';
-import { convertIntegrationFnToClass, getCurrentScope } from '@sentry/core';
+import { convertIntegrationFnToClass, defineIntegration, getCurrentScope } from '@sentry/core';
 import type { Client, Contexts, Event, EventHint, Integration, IntegrationClass, IntegrationFn } from '@sentry/types';
 import { dynamicRequire, logger } from '@sentry/utils';
 import type { Worker, WorkerOptions } from 'worker_threads';
@@ -52,7 +52,7 @@ interface InspectorApi {
 
 const INTEGRATION_NAME = 'Anr';
 
-const anrIntegration = ((options: Partial<AnrIntegrationOptions> = {}) => {
+const _anrIntegration = ((options: Partial<AnrIntegrationOptions> = {}) => {
   return {
     name: INTEGRATION_NAME,
     // TODO v8: Remove this
@@ -68,10 +68,14 @@ const anrIntegration = ((options: Partial<AnrIntegrationOptions> = {}) => {
   };
 }) satisfies IntegrationFn;
 
+export const anrIntegration = defineIntegration(_anrIntegration);
+
 /**
  * Starts a thread to detect App Not Responding (ANR) events
  *
  * ANR detection requires Node 16.17.0 or later
+ *
+ * @deprecated Use `anrIntegration()` instead.
  */
 // eslint-disable-next-line deprecation/deprecation
 export const Anr = convertIntegrationFnToClass(INTEGRATION_NAME, anrIntegration) as IntegrationClass<
@@ -80,6 +84,9 @@ export const Anr = convertIntegrationFnToClass(INTEGRATION_NAME, anrIntegration)
   new (options?: Partial<AnrIntegrationOptions>): Integration & { setup(client: Client): void };
 };
 
+// eslint-disable-next-line deprecation/deprecation
+export type Anr = typeof Anr;
+
 /**
  * Starts the ANR worker thread
  */

packages/node/src/integrations/anr/legacy.ts

@@ -26,6 +26,7 @@ interface LegacyOptions {
  */
 export function enableAnrDetection(options: Partial<LegacyOptions>): Promise<void> {
   const client = getClient() as NodeClient;
+  // eslint-disable-next-line deprecation/deprecation
   const integration = new Anr(options);
   integration.setup(client);
   return Promise.resolve();

packages/node/src/integrations/console.ts

@@ -1,11 +1,11 @@
 import * as util from 'util';
-import { addBreadcrumb, convertIntegrationFnToClass, getClient } from '@sentry/core';
+import { addBreadcrumb, convertIntegrationFnToClass, defineIntegration, getClient } from '@sentry/core';
 import type { Client, Integration, IntegrationClass, IntegrationFn } from '@sentry/types';
 import { addConsoleInstrumentationHandler, severityLevelFromString } from '@sentry/utils';
 
 const INTEGRATION_NAME = 'Console';
 
-const consoleIntegration = (() => {
+const _consoleIntegration = (() => {
   return {
     name: INTEGRATION_NAME,
     // TODO v8: Remove this
@@ -32,8 +32,16 @@ const consoleIntegration = (() => {
   };
 }) satisfies IntegrationFn;
 
-/** Console module integration */
+export const consoleIntegration = defineIntegration(_consoleIntegration);
+
+/**
+ * Console module integration.
+ * @deprecated Use `consoleIntegration()` instead.
+ */
 // eslint-disable-next-line deprecation/deprecation
 export const Console = convertIntegrationFnToClass(INTEGRATION_NAME, consoleIntegration) as IntegrationClass<
   Integration & { setup: (client: Client) => void }
 >;
+
+// eslint-disable-next-line deprecation/deprecation
+export type Console = typeof Console;

packages/node/src/integrations/context.ts

@@ -4,7 +4,7 @@ import { readFile, readdir } from 'fs';
 import * as os from 'os';
 import { join } from 'path';
 import { promisify } from 'util';
-import { convertIntegrationFnToClass } from '@sentry/core';
+import { convertIntegrationFnToClass, defineIntegration } from '@sentry/core';
 import type {
   AppContext,
   CloudResourceContext,
@@ -37,7 +37,7 @@ interface ContextOptions {
   cloudResource?: boolean;
 }
 
-const nodeContextIntegration = ((options: ContextOptions = {}) => {
+const _nodeContextIntegration = ((options: ContextOptions = {}) => {
   let cachedContext: Promise<Contexts> | undefined;
 
   const _options = {
@@ -110,7 +110,12 @@ const nodeContextIntegration = ((options: ContextOptions = {}) => {
   };
 }) satisfies IntegrationFn;
 
-/** Add node modules / packages to the event */
+export const nodeContextIntegration = defineIntegration(_nodeContextIntegration);
+
+/**
+ * Add node modules / packages to the event.
+ * @deprecated Use `nodeContextIntegration()` instead.
+ */
 // eslint-disable-next-line deprecation/deprecation
 export const Context = convertIntegrationFnToClass(INTEGRATION_NAME, nodeContextIntegration) as IntegrationClass<
   Integration & { processEvent: (event: Event) => Promise<Event> }
@@ -124,6 +129,9 @@ export const Context = convertIntegrationFnToClass(INTEGRATION_NAME, nodeContext
   }): Integration;
 };
 
+// eslint-disable-next-line deprecation/deprecation
+export type Context = typeof Context;
+
 /**
  * Updates the context with dynamic values that can change
  */

packages/node/src/integrations/contextlines.ts

@@ -1,5 +1,5 @@
 import { readFile } from 'fs';
-import { convertIntegrationFnToClass } from '@sentry/core';
+import { convertIntegrationFnToClass, defineIntegration } from '@sentry/core';
 import type { Event, Integration, IntegrationClass, IntegrationFn, StackFrame } from '@sentry/types';
 import { LRUMap, addContextToFrame } from '@sentry/utils';
 
@@ -35,7 +35,7 @@ interface ContextLinesOptions {
   frameContextLines?: number;
 }
 
-const contextLinesIntegration = ((options: ContextLinesOptions = {}) => {
+const _contextLinesIntegration = ((options: ContextLinesOptions = {}) => {
   const contextLines = options.frameContextLines !== undefined ? options.frameContextLines : DEFAULT_LINES_OF_CONTEXT;
 
   return {
@@ -48,7 +48,12 @@ const contextLinesIntegration = ((options: ContextLinesOptions = {}) => {
   };
 }) satisfies IntegrationFn;
 
-/** Add node modules / packages to the event */
+export const contextLinesIntegration = defineIntegration(_contextLinesIntegration);
+
+/**
+ * Add node modules / packages to the event.
+ * @deprecated Use `contextLinesIntegration()` instead.
+ */
 // eslint-disable-next-line deprecation/deprecation
 export const ContextLines = convertIntegrationFnToClass(INTEGRATION_NAME, contextLinesIntegration) as IntegrationClass<
   Integration & { processEvent: (event: Event) => Promise<Event> }
@@ -119,6 +124,9 @@ function addSourceContextToFrames(frames: StackFrame[], contextLines: number): v
   }
 }
 
+// eslint-disable-next-line deprecation/deprecation
+export type ContextLines = typeof ContextLines;
+
 /**
  * Reads file contents and caches them in a global LRU cache.
  * If reading fails, mark the file as null in the cache so we don't try again.

packages/node/src/integrations/hapi/index.ts

@@ -3,6 +3,7 @@ import {
   captureException,
   continueTrace,
   convertIntegrationFnToClass,
+  defineIntegration,
   getActiveTransaction,
   getCurrentScope,
   getDynamicSamplingContextFromSpan,
@@ -139,7 +140,7 @@ export type HapiOptions = {
 
 const INTEGRATION_NAME = 'Hapi';
 
-const hapiIntegration = ((options: HapiOptions = {}) => {
+const _hapiIntegration = ((options: HapiOptions = {}) => {
   const server = options.server as undefined | Server;
 
   return {
@@ -161,8 +162,14 @@ const hapiIntegration = ((options: HapiOptions = {}) => {
   };
 }) satisfies IntegrationFn;
 
+export const hapiIntegration = defineIntegration(_hapiIntegration);
+
 /**
- * Hapi Framework Integration
+ * Hapi Framework Integration.
+ * @deprecated Use `hapiIntegration()` instead.
  */
 // eslint-disable-next-line deprecation/deprecation
 export const Hapi = convertIntegrationFnToClass(INTEGRATION_NAME, hapiIntegration);
+
+// eslint-disable-next-line deprecation/deprecation
+export type Hapi = typeof Hapi;

packages/node/src/integrations/http.ts

@@ -1,7 +1,7 @@
 import type * as http from 'http';
 import type * as https from 'https';
 import type { Hub } from '@sentry/core';
-import { getIsolationScope } from '@sentry/core';
+import { getIsolationScope, defineIntegration } from '@sentry/core';
 import {
   addBreadcrumb,
   getActiveSpan,
@@ -15,7 +15,15 @@ import {
   spanToJSON,
   spanToTraceHeader,
 } from '@sentry/core';
-import type { EventProcessor, Integration, SanitizedRequestData, TracePropagationTargets } from '@sentry/types';
+import type {
+  DynamicSamplingContext,
+  EventProcessor,
+  Integration,
+  IntegrationFn,
+  IntegrationFnResult,
+  SanitizedRequestData,
+  TracePropagationTargets,
+} from '@sentry/types';
 import {
   LRUMap,
   dynamicSamplingContextToSentryBaggageHeader,
@@ -72,9 +80,18 @@ interface HttpOptions {
   tracing?: TracingOptions | boolean;
 }
 
+const _httpIntegration = ((options?: HttpOptions) => {
+  // eslint-disable-next-line deprecation/deprecation
+  return new Http(options) as unknown as IntegrationFnResult;
+}) satisfies IntegrationFn;
+
+export const httpIntegration = defineIntegration(_httpIntegration);
+
 /**
  * The http module integration instruments Node's internal http module. It creates breadcrumbs, transactions for outgoing
  * http requests and attaches trace data when tracing is enabled via its `tracing` option.
+ *
+ * @deprecated Use `httpIntegration()` instead.
  */
 export class Http implements Integration {
   /**
@@ -85,6 +102,7 @@ export class Http implements Integration {
   /**
    * @inheritDoc
    */
+  // eslint-disable-next-line deprecation/deprecation
   public name: string = Http.id;
 
   private readonly _breadcrumbs: boolean;

packages/node/src/integrations/index.ts

@@ -1,11 +1,11 @@
+/* eslint-disable deprecation/deprecation */
 export { Console } from './console';
 export { Http } from './http';
 export { OnUncaughtException } from './onuncaughtexception';
 export { OnUnhandledRejection } from './onunhandledrejection';
 export { Modules } from './modules';
 export { ContextLines } from './contextlines';
 export { Context } from './context';
-// eslint-disable-next-line deprecation/deprecation
 export { RequestData } from '@sentry/core';
 export { LocalVariables } from './local-variables';
 export { Undici } from './undici';

packages/node/src/integrations/local-variables/index.ts

@@ -1,6 +1,13 @@
-import { LocalVariablesSync } from './local-variables-sync';
+import { LocalVariablesSync, localVariablesSyncIntegration } from './local-variables-sync';
 
 /**
- * Adds local variables to exception frames
+ * Adds local variables to exception frames.
+ *
+ * @deprecated Use `localVariablesIntegration()` instead.
  */
+// eslint-disable-next-line deprecation/deprecation
 export const LocalVariables = LocalVariablesSync;
+// eslint-disable-next-line deprecation/deprecation
+export type LocalVariables = LocalVariablesSync;
+
+export const localVariablesIntegration = localVariablesSyncIntegration;

packages/node/src/integrations/local-variables/local-variables-async.ts

@@ -1,5 +1,5 @@
 import type { Session } from 'node:inspector/promises';
-import { convertIntegrationFnToClass } from '@sentry/core';
+import { convertIntegrationFnToClass, defineIntegration } from '@sentry/core';
 import type { Event, Exception, Integration, IntegrationClass, IntegrationFn, StackParser } from '@sentry/types';
 import { LRUMap, dynamicRequire, logger } from '@sentry/utils';
 import type { Debugger, InspectorNotification, Runtime } from 'inspector';
@@ -76,7 +76,7 @@ const INTEGRATION_NAME = 'LocalVariablesAsync';
 /**
  * Adds local variables to exception frames
  */
-const localVariablesAsyncIntegration = ((options: LocalVariablesIntegrationOptions = {}) => {
+const _localVariablesAsyncIntegration = ((options: LocalVariablesIntegrationOptions = {}) => {
   const cachedFrames: LRUMap<string, FrameVariables[]> = new LRUMap(20);
   let rateLimiter: RateLimitIncrement | undefined;
   let shouldProcessEvent = false;
@@ -253,11 +253,17 @@ const localVariablesAsyncIntegration = ((options: LocalVariablesIntegrationOptio
   };
 }) satisfies IntegrationFn;
 
+export const localVariablesAsyncIntegration = defineIntegration(_localVariablesAsyncIntegration);
+
 /**
- * Adds local variables to exception frames
+ * Adds local variables to exception frames.
+ * @deprecated Use `localVariablesAsyncIntegration()` instead.
  */
 // eslint-disable-next-line deprecation/deprecation
 export const LocalVariablesAsync = convertIntegrationFnToClass(
   INTEGRATION_NAME,
   localVariablesAsyncIntegration,
 ) as IntegrationClass<Integration & { processEvent: (event: Event) => Event; setup: (client: NodeClient) => void }>;
+
+// eslint-disable-next-line deprecation/deprecation
+export type LocalVariablesAsync = typeof LocalVariablesAsync;

packages/node/src/integrations/local-variables/local-variables-sync.ts

@@ -1,5 +1,5 @@
 /* eslint-disable max-lines */
-import { convertIntegrationFnToClass, getClient } from '@sentry/core';
+import { convertIntegrationFnToClass, defineIntegration, getClient } from '@sentry/core';
 import type { Event, Exception, Integration, IntegrationClass, IntegrationFn, StackParser } from '@sentry/types';
 import { LRUMap, logger } from '@sentry/utils';
 import type { Debugger, InspectorNotification, Runtime, Session } from 'inspector';
@@ -219,7 +219,7 @@ const INTEGRATION_NAME = 'LocalVariables';
 /**
  * Adds local variables to exception frames
  */
-const localVariablesSyncIntegration = ((
+const _localVariablesSyncIntegration = ((
   options: LocalVariablesIntegrationOptions = {},
   session: DebugSession | undefined = tryNewAsyncSession(),
 ) => {
@@ -392,8 +392,11 @@ const localVariablesSyncIntegration = ((
   };
 }) satisfies IntegrationFn;
 
+export const localVariablesSyncIntegration = defineIntegration(_localVariablesSyncIntegration);
+
 /**
- * Adds local variables to exception frames
+ * Adds local variables to exception frames.
+ * @deprecated Use `localVariablesSyncIntegration()` instead.
  */
 // eslint-disable-next-line deprecation/deprecation
 export const LocalVariablesSync = convertIntegrationFnToClass(
@@ -402,3 +405,6 @@ export const LocalVariablesSync = convertIntegrationFnToClass(
 ) as IntegrationClass<Integration & { processEvent: (event: Event) => Event; setup: (client: NodeClient) => void }> & {
   new (options?: LocalVariablesIntegrationOptions, session?: DebugSession): Integration;
 };
+
+// eslint-disable-next-line deprecation/deprecation
+export type LocalVariablesSync = typeof LocalVariablesSync;