fix(node-experimental): Update auto integration lookup & readme (#8690)

This updates the way we auto-lookup integrations.

Due to how OTEL instrumentation works, we actually do not need any
dynamic require. Otel instrumentation will generally always work, it
only actually instruments when something is required/imported. So all
integration _will_ be added, they will simply do nothing if the package
is not used.

This also updates the readme to clarify this & restrictions.

Author: mydea

packages/node-experimental/README.md

@@ -50,10 +50,26 @@ Currently, this SDK:
 * Will capture errors (same as @sentry/node)
 * Auto-instrument for performance - see below for which performance integrations are available.
 
+### Manual Instrumentation
+
 **Manual instrumentation is not supported!**
 This is because the current Sentry-Performance-APIs like `Sentry.startTransaction()` are not compatible with the OpenTelemetry tracing model.
 We may add manual tracing capabilities in a later version.
 
+### ESM Support
+
+Due to the way OpenTelemetry handles instrumentation, this only works out of the box for CommonJS (`require`) applications.
+
+
+There is experimental support for running OpenTelemetry with ESM (`"type": "module"`):
+
+```bash
+node --experimental-loader=@opentelemetry/instrumentation/hook.mjs ./app.js
+```
+
+See [OpenTelemetry Instrumentation Docs](https://github.com/open-telemetry/opentelemetry-js/tree/main/experimental/packages/opentelemetry-instrumentation#instrumentation-for-es-modules-in-nodejs-experimental) for details on this -
+but note that this is a) experimental, and b) does not work with all integrations.
+
 ## Available (Performance) Integrations
 
 * Http

packages/node-experimental/src/integrations/lazy.ts renamed to packages/node-experimental/src/integrations/NodePerformanceIntegration.ts

@@ -1,20 +1,39 @@
 import type { Instrumentation } from '@opentelemetry/instrumentation';
 import { registerInstrumentations } from '@opentelemetry/instrumentation';
 
-/** TODO */
+/**
+ * The base node performance integration.
+ */
 export abstract class NodePerformanceIntegration<IntegrationOptions> {
   protected _options: IntegrationOptions;
   protected _unload?: () => void;
+  protected _instrumentations?: Instrumentation[] | undefined;
+
+  public abstract name: string;
 
   public constructor(options: IntegrationOptions) {
     this._options = options;
   }
 
+  /**
+   * Load the instrumentation(s) for this integration.
+   * Returns `true` if the instrumentations were loaded, else false.
+   */
+  public loadInstrumentations(): boolean {
+    try {
+      this._instrumentations = this.setupInstrumentation(this._options) || undefined;
+    } catch (error) {
+      return false;
+    }
+
+    return true;
+  }
+
   /**
    * @inheritDoc
    */
   public setupOnce(): void {
-    const instrumentations = this.setupInstrumentation(this._options);
+    const instrumentations = this._instrumentations || this.setupInstrumentation(this._options);
 
     if (!instrumentations) {
       return;

packages/node-experimental/src/integrations/express.ts

@@ -2,7 +2,7 @@ import type { Instrumentation } from '@opentelemetry/instrumentation';
 import { ExpressInstrumentation } from '@opentelemetry/instrumentation-express';
 import type { Integration } from '@sentry/types';
 
-import { NodePerformanceIntegration } from './lazy';
+import { NodePerformanceIntegration } from './NodePerformanceIntegration';
 
 /**
  * Express integration

packages/node-experimental/src/integrations/fastify.ts

@@ -2,7 +2,7 @@ import type { Instrumentation } from '@opentelemetry/instrumentation';
 import { FastifyInstrumentation } from '@opentelemetry/instrumentation-fastify';
 import type { Integration } from '@sentry/types';
 
-import { NodePerformanceIntegration } from './lazy';
+import { NodePerformanceIntegration } from './NodePerformanceIntegration';
 
 /**
  * Express integration

packages/node-experimental/src/integrations/getAutoPerformanceIntegrations.ts

@@ -1,87 +1,67 @@
-import type { Integration, IntegrationClass } from '@sentry/types';
-import { dynamicRequire } from '@sentry/utils';
+import type { Integration } from '@sentry/types';
 
-import type { Express } from './express';
-import type { Fastify } from './fastify';
-import type { GraphQL } from './graphql';
-import type { Mongo } from './mongo';
-import type { Mongoose } from './mongoose';
-import type { Mysql } from './mysql';
-import type { Mysql2 } from './mysql2';
-import type { Nest } from './nest';
-import type { Postgres } from './postgres';
-import type { Prisma } from './prisma';
+import { Express } from './express';
+import { Fastify } from './fastify';
+import { GraphQL } from './graphql';
+import { Mongo } from './mongo';
+import { Mongoose } from './mongoose';
+import { Mysql } from './mysql';
+import { Mysql2 } from './mysql2';
+import { Nest } from './nest';
+import type { NodePerformanceIntegration } from './NodePerformanceIntegration';
+import { Postgres } from './postgres';
+import { Prisma } from './prisma';
 
-const INTEGRATIONS = [
+const INTEGRATIONS: (() => NodePerformanceIntegration<unknown>)[] = [
   () => {
-    const integration = dynamicRequire(module, './express') as {
-      Express: IntegrationClass<Express>;
-    };
-    return new integration.Express();
+    return new Express();
   },
   () => {
-    const integration = dynamicRequire(module, './fastify') as {
-      Fastify: IntegrationClass<Fastify>;
-    };
-    return new integration.Fastify();
+    return new Fastify();
   },
   () => {
-    const integration = dynamicRequire(module, './graphql') as {
-      GraphQL: IntegrationClass<GraphQL>;
-    };
-    return new integration.GraphQL();
+    return new GraphQL();
   },
   () => {
-    const integration = dynamicRequire(module, './mongo') as {
-      Mongo: IntegrationClass<Mongo>;
-    };
-    return new integration.Mongo();
+    return new Mongo();
   },
   () => {
-    const integration = dynamicRequire(module, './mongoose') as {
-      Mongoose: IntegrationClass<Mongoose>;
-    };
-    return new integration.Mongoose();
+    return new Mongoose();
   },
   () => {
-    const integration = dynamicRequire(module, './mysql') as {
-      Mysql: IntegrationClass<Mysql>;
-    };
-    return new integration.Mysql();
+    return new Mysql();
   },
   () => {
-    const integration = dynamicRequire(module, './mysql2') as {
-      Mysql2: IntegrationClass<Mysql2>;
-    };
-    return new integration.Mysql2();
+    return new Mysql2();
   },
   () => {
-    const integration = dynamicRequire(module, './postgres') as {
-      Postgres: IntegrationClass<Postgres>;
-    };
-    return new integration.Postgres();
+    return new Postgres();
   },
   () => {
-    const integration = dynamicRequire(module, './prisma') as {
-      Prisma: IntegrationClass<Prisma>;
-    };
-    return new integration.Prisma();
+    return new Prisma();
   },
   () => {
-    const integration = dynamicRequire(module, './nest') as {
-      Nest: IntegrationClass<Nest>;
-    };
-    return new integration.Nest();
+    return new Nest();
   },
 ];
 
-/** TODO */
+/**
+ * Get auto-dsicovered performance integrations.
+ * Note that due to the way OpenTelemetry instrumentation works, this will generally still return Integrations
+ * for stuff that may not be installed. This is because Otel only instruments when the module is imported/required,
+ * so if the package is not required at all it will not be patched, and thus not instrumented.
+ * But the _Sentry_ Integration will still be added.
+ * This _may_ be a bit confusing because it shows all integrations as being installed in the debug logs, but this is
+ * technically not wrong because we install it (it just doesn't do anything).
+ */
 export function getAutoPerformanceIntegrations(): Integration[] {
   const loadedIntegrations = INTEGRATIONS.map(tryLoad => {
     try {
-      return tryLoad();
+      const integration = tryLoad();
+      const isLoaded = integration.loadInstrumentations();
+      return isLoaded ? integration : false;
     } catch (_) {
-      return undefined;
+      return false;
     }
   }).filter(integration => !!integration) as Integration[];
 

packages/node-experimental/src/integrations/graphql.ts

@@ -2,7 +2,7 @@ import type { Instrumentation } from '@opentelemetry/instrumentation';
 import { GraphQLInstrumentation } from '@opentelemetry/instrumentation-graphql';
 import type { Integration } from '@sentry/types';
 
-import { NodePerformanceIntegration } from './lazy';
+import { NodePerformanceIntegration } from './NodePerformanceIntegration';
 
 /**
  * GraphQL integration

packages/node-experimental/src/integrations/mongo.ts

@@ -2,7 +2,7 @@ import type { Instrumentation } from '@opentelemetry/instrumentation';
 import { MongoDBInstrumentation } from '@opentelemetry/instrumentation-mongodb';
 import type { Integration } from '@sentry/types';
 
-import { NodePerformanceIntegration } from './lazy';
+import { NodePerformanceIntegration } from './NodePerformanceIntegration';
 
 /**
  * MongoDB integration

packages/node-experimental/src/integrations/mongoose.ts

@@ -2,7 +2,7 @@ import type { Instrumentation } from '@opentelemetry/instrumentation';
 import { MongooseInstrumentation } from '@opentelemetry/instrumentation-mongoose';
 import type { Integration } from '@sentry/types';
 
-import { NodePerformanceIntegration } from './lazy';
+import { NodePerformanceIntegration } from './NodePerformanceIntegration';
 
 /**
  * Mongoose integration

packages/node-experimental/src/integrations/mysql.ts

@@ -2,7 +2,7 @@ import type { Instrumentation } from '@opentelemetry/instrumentation';
 import { MySQLInstrumentation } from '@opentelemetry/instrumentation-mysql';
 import type { Integration } from '@sentry/types';
 
-import { NodePerformanceIntegration } from './lazy';
+import { NodePerformanceIntegration } from './NodePerformanceIntegration';
 
 /**
  * MySQL integration

packages/node-experimental/src/integrations/mysql2.ts

@@ -2,7 +2,7 @@ import type { Instrumentation } from '@opentelemetry/instrumentation';
 import { MySQL2Instrumentation } from '@opentelemetry/instrumentation-mysql2';
 import type { Integration } from '@sentry/types';
 
-import { NodePerformanceIntegration } from './lazy';
+import { NodePerformanceIntegration } from './NodePerformanceIntegration';
 
 /**
  * MySQL2 integration