feat: Deprecate registerEsmLoaderHooks.include and registerEsmLoaderHooks.exclude (#14486)

Author: lforst

dev-packages/node-integration-tests/suites/esm/warn-esm/test.ts

@@ -5,7 +5,7 @@ afterAll(() => {
 });
 
 const esmWarning =
-  '[Sentry] You are using Node.js in ESM mode ("import syntax"). The Sentry Node.js SDK is not compatible with ESM in Node.js versions before 18.19.0 or before 20.6.0. Please either build your application with CommonJS ("require() syntax"), or use version 7.x of the Sentry Node.js SDK.';
+  '[Sentry] You are using Node.js in ESM mode ("import syntax"). The Sentry Node.js SDK is not compatible with ESM in Node.js versions before 18.19.0 or before 20.6.0. Please either build your application with CommonJS ("require() syntax"), or upgrade your Node.js version.';
 
 test("warns if using ESM on Node.js versions that don't support `register()`", async () => {
   const nodeMajorVersion = Number(process.versions.node.split('.')[0]);

docs/migration/draft-v9-migration-guide.md

@@ -90,3 +90,5 @@
 - Deprecated `processThreadBreadcrumbIntegration` in favor of `childProcessIntegration`. Functionally they are the same.
 - Deprecated `nestIntegration`. Use the NestJS SDK (`@sentry/nestjs`) instead.
 - Deprecated `setupNestErrorHandler`. Use the NestJS SDK (`@sentry/nestjs`) instead.
+- Deprecated `registerEsmLoaderHooks.include` and `registerEsmLoaderHooks.exclude`. Set `onlyIncludeInstrumentedModules: true` instead.
+- `registerEsmLoaderHooks` will only accept `true | false | undefined` in the future. The SDK will default to wrapping modules that are used as part of OpenTelemetry Instrumentation.

packages/node/src/sdk/initOtel.ts

@@ -42,10 +42,12 @@ interface RegisterOptions {
 }
 
 function getRegisterOptions(esmHookConfig?: EsmLoaderHookOptions): RegisterOptions {
+  // TODO(v9): Make onlyIncludeInstrumentedModules: true the default behavior.
   if (esmHookConfig?.onlyIncludeInstrumentedModules) {
     const { addHookMessagePort } = createAddHookMessageChannel();
     // If the user supplied include, we need to use that as a starting point or use an empty array to ensure no modules
     // are wrapped if they are not hooked
+    // eslint-disable-next-line deprecation/deprecation
     return { data: { addHookMessagePort, include: esmHookConfig.include || [] }, transferList: [addHookMessagePort] };
   }
 
@@ -75,7 +77,7 @@ export function maybeInitializeEsmLoader(esmHookConfig?: EsmLoaderHookOptions):
     consoleSandbox(() => {
       // eslint-disable-next-line no-console
       console.warn(
-        '[Sentry] You are using Node.js in ESM mode ("import syntax"). The Sentry Node.js SDK is not compatible with ESM in Node.js versions before 18.19.0 or before 20.6.0. Please either build your application with CommonJS ("require() syntax"), or use version 7.x of the Sentry Node.js SDK.',
+        '[Sentry] You are using Node.js in ESM mode ("import syntax"). The Sentry Node.js SDK is not compatible with ESM in Node.js versions before 18.19.0 or before 20.6.0. Please either build your application with CommonJS ("require() syntax"), or upgrade your Node.js version.',
       );
     });
   }

packages/node/src/types.ts

@@ -5,9 +5,26 @@ import type { ClientOptions, Options, SamplingContext, Scope, Span, TracePropaga
 
 import type { NodeTransportOptions } from './transports';
 
+/**
+ * Note: In the next major version of the Sentry SDK this interface will be removed and the SDK will by default only wrap
+ * ESM modules that are required to be wrapped by OpenTelemetry Instrumentation.
+ */
 export interface EsmLoaderHookOptions {
+  /**
+   * Provide a list of modules to wrap with `import-in-the-middle`.
+   *
+   * @deprecated It is recommended to use `onlyIncludeInstrumentedModules: true` instead of manually defining modules to include and exclude.
+   */
   include?: Array<string | RegExp>;
-  exclude?: Array<string | RegExp> /**
+
+  /**
+   * Provide a list of modules to prevent them from being wrapped with `import-in-the-middle`.
+   *
+   * @deprecated It is recommended to use `onlyIncludeInstrumentedModules: true` instead of manually defining modules to include and exclude.
+   */
+  exclude?: Array<string | RegExp>;
+
+  /**
    * When set to `true`, `import-in-the-middle` will only wrap ESM modules that are specifically instrumented by
    * OpenTelemetry plugins. This is useful to avoid issues where `import-in-the-middle` is not compatible with some of
    * your dependencies.
@@ -17,7 +34,11 @@ export interface EsmLoaderHookOptions {
    * `Sentry.init()`.
    *
    * Defaults to `false`.
-   */;
+   *
+   * Note: In the next major version of the Sentry SDK this option will be removed and the SDK will by default only wrap
+   * ESM modules that are required to be wrapped by OpenTelemetry Instrumentation.
+   */
+  // TODO(v9): Make `onlyIncludeInstrumentedModules: true` the default behavior.
   onlyIncludeInstrumentedModules?: boolean;
 }
 
@@ -88,6 +109,8 @@ export interface BaseNodeOptions {
    * * The `SentryPropagator`
    * * The `SentryContextManager`
    * * The `SentrySampler`
+   *
+   * If you are registering your own OpenTelemetry Loader Hooks (or `import-in-the-middle` hooks), it is also recommended to set the `registerEsmLoaderHooks` option to false.
    */
   skipOpenTelemetrySetup?: boolean;
 
@@ -125,7 +148,11 @@ export interface BaseNodeOptions {
    * ```
    *
    * Defaults to `true`.
+   *
+   * Note: In the next major version of the SDK, the possibility to provide fine-grained control will be removed from this option.
+   * This means that it will only be possible to pass `true` or `false`. The default value will continue to be `true`.
    */
+  // TODO(v9): Only accept true | false | undefined.
   registerEsmLoaderHooks?: boolean | EsmLoaderHookOptions;
 
   /**

packages/nuxt/src/server/sdk.ts

@@ -100,9 +100,12 @@ export function mergeRegisterEsmLoaderHooks(
 ): SentryNuxtServerOptions['registerEsmLoaderHooks'] {
   if (typeof options.registerEsmLoaderHooks === 'object' && options.registerEsmLoaderHooks !== null) {
     return {
+      // eslint-disable-next-line deprecation/deprecation
       exclude: Array.isArray(options.registerEsmLoaderHooks.exclude)
-        ? [...options.registerEsmLoaderHooks.exclude, /vue/]
-        : options.registerEsmLoaderHooks.exclude ?? [/vue/],
+        ? // eslint-disable-next-line deprecation/deprecation
+          [...options.registerEsmLoaderHooks.exclude, /vue/]
+        : // eslint-disable-next-line deprecation/deprecation
+          options.registerEsmLoaderHooks.exclude ?? [/vue/],
     };
   }
   return options.registerEsmLoaderHooks ?? { exclude: [/vue/] };