fix(node): do not pass options to orchestrion opt-in

This resolves the API surface wart where options for orchestrion
integrations had to be passed into the
`experimentalUseDiagnosticsChannelInjection` method, and returns that to
being an argument-free void-returning opt-in that can be easily no-op'ed
in the future, and all options are passed in via `Sentry.init()` as they
were in the prior OTel implementation.

Author: isaacs

packages/node/src/integrations/tracing/mysql/index.ts

@@ -2,12 +2,20 @@ import { MySQLInstrumentation } from './vendored/instrumentation';
 import type { IntegrationFn } from '@sentry/core';
 import { defineIntegration } from '@sentry/core';
 import { generateInstrumentOnce } from '@sentry/node-core';
+import { getChannelIntegrationFactory } from '../../../sdk/diagnosticsChannelInjection';
 
 const INTEGRATION_NAME = 'Mysql' as const;
 
 export const instrumentMysql = generateInstrumentOnce(INTEGRATION_NAME, () => new MySQLInstrumentation({}));
 
 const _mysqlIntegration = (() => {
+  // When opted into diagnostics-channel injection, build
+  // orchestrion implementation instead, with same options.
+  const channelIntegration = getChannelIntegrationFactory(INTEGRATION_NAME);
+  if (channelIntegration) {
+    return channelIntegration();
+  }
+
   return {
     name: INTEGRATION_NAME,
     setupOnce() {

packages/node/src/integrations/tracing/postgres/index.ts

@@ -2,6 +2,7 @@ import { PgInstrumentation } from './vendored/instrumentation';
 import type { IntegrationFn } from '@sentry/core';
 import { defineIntegration } from '@sentry/core';
 import { generateInstrumentOnce } from '@sentry/node-core';
+import { getChannelIntegrationFactory } from '../../../sdk/diagnosticsChannelInjection';
 
 interface PostgresIntegrationOptions {
   ignoreConnectSpans?: boolean;
@@ -18,6 +19,13 @@ export const instrumentPostgres = generateInstrumentOnce(
 );
 
 const _postgresIntegration = ((options?: PostgresIntegrationOptions) => {
+  // When opted into diagnostics-channel injection, build
+  // orchestrion implementation instead, with same options.
+  const channelIntegration = getChannelIntegrationFactory(INTEGRATION_NAME);
+  if (channelIntegration) {
+    return channelIntegration(options);
+  }
+
   return {
     name: INTEGRATION_NAME,
     setupOnce() {

packages/node/src/sdk/diagnosticsChannelInjection.ts

@@ -1,4 +1,4 @@
-import type { Integration } from '@sentry/core';
+import type { IntegrationFn } from '@sentry/core';
 
 /**
  * The orchestrion-driven pieces, resolved lazily by the opt-in loader.
@@ -13,10 +13,15 @@ import type { Integration } from '@sentry/core';
  * normally.
  */
 export interface DiagnosticsChannelInjection {
-  /** Channel-based integrations to register, replacing their OTel equivalents. */
-  integrations: Integration[];
-  /** OTel integration names these replace; filtered out of the default set. */
-  replacedOtelIntegrationNames: string[];
+  /**
+   * Channel-based integration factories, keyed by the OTel integration name
+   * they replace (e.g. `Postgres`). The matching OTel integration factory
+   * (e.g. `postgresIntegration()`) looks itself up here and, when present,
+   * builds the channel implementation instead, forwarding the user's options.
+   * This is how opting in swaps implementations without the OTel factory
+   * ever importing the orchestrion code (which would defeat tree-shaking).
+   */
+  integrationFactories: Record<string, IntegrationFn>;
   /** Installs the module hooks that inject the diagnostics channels. */
   register: () => void;
   /** Warns (DEBUG only) about missing or doubled channel injection. */
@@ -35,6 +40,8 @@ let cached: DiagnosticsChannelInjection | undefined;
  */
 export function setDiagnosticsChannelInjectionLoader(load: () => DiagnosticsChannelInjection): void {
   loader = load;
+  // A new loader invalidates anything memoized from a previous one.
+  cached = undefined;
 }
 
 /** Whether `experimentalUseDiagnosticsChannelInjection()` was called. */
@@ -54,3 +61,23 @@ export function resolveDiagnosticsChannelInjection(): DiagnosticsChannelInjectio
   }
   return (cached ??= loader());
 }
+
+/**
+ * The channel-based integration factory registered to replace the OTel
+ * integration named `name` (e.g. `Postgres`), or `undefined` when the app
+ * didn't opt into diagnostics-channel injection. Node integration factories
+ * call this to decide whether to build the orchestrion implementation (with
+ * the user's options) instead of the OTel one, without ever importing
+ * orchestrion directly.
+ *
+ * @internal
+ */
+export function getChannelIntegrationFactory(name: string): IntegrationFn | undefined {
+  return resolveDiagnosticsChannelInjection()?.integrationFactories[name];
+}
+
+/** Test-only: clear the registered loader and memoized result. */
+export function _resetDiagnosticsChannelInjectionForTesting(): void {
+  loader = undefined;
+  cached = undefined;
+}

packages/node/src/sdk/experimentalUseDiagnosticsChannelInjection.ts

@@ -27,35 +27,45 @@ import { setDiagnosticsChannelInjectionLoader } from './diagnosticsChannelInject
  * OpenTelemetry ones, and installs the module hooks that inject the channels
  * (so libraries imported after `init()` publish the channel events).
  *
+ * The swap is per-integration and transparent: the OTel integration factories
+ * build their channel equivalent when this has been called, so you configure
+ * them exactly as before.
+ *
+ * For example, to suppress pg connect spans on the orchestrion path:
+ *
+ * ```ts
+ * Sentry.experimentalUseDiagnosticsChannelInjection();
+ * Sentry.init({
+ *   dsn: '__DSN__',
+ *   integrations: [Sentry.postgresIntegration({ ignoreConnectSpans: true })],
+ * });
+ * ```
+ *
  * This is a standalone function rather than an `init()` option so that a
  * bundler drops all of it (and its transitive deps) when this function isn't
- * called. `init()` reads the loader registered below.
+ * called. The integration factories reach the channel implementations only via
+ * the registry populated below, so they never import the orchestrion code
+ * themselves, keeping the tree-shaking boundary at this function.
  *
  * An app that DOES call it gets the orchestrion code bundled as intended.
  *
  * In an unbundled (server-side runtime) app this eagerly loads only the small
  * subscriber/channel modules; the heavy code-transform dependencies stay lazy
  * inside `register()` and load only when injection actually runs.
  *
- * Per-integration options are passed here rather than via the OTel
- * `xxxIntegration({...})` instances, because those are swapped out wholesale for
- * their channel equivalents (and a user-provided OTel instance would otherwise
- * win integration de-duplication, silently keeping the OTel path). For example,
- * to suppress pg connect spans on the orchestrion path:
- *
- * ```ts
- * Sentry.experimentalUseDiagnosticsChannelInjection({ postgres: { ignoreConnectSpans: true } });
- * ```
- *
  * @experimental May change or be removed in any release.
  */
-export function experimentalUseDiagnosticsChannelInjection(
-  options: { postgres?: { ignoreConnectSpans?: boolean } } = {},
-): void {
+// Note: This function is to remain argument-free and void-returning so that
+// it can be easily no-op'ed (or provided with a `false` flag or something to
+// opt-out) when orchestrion becomes the default.
+export function experimentalUseDiagnosticsChannelInjection(): void {
   setDiagnosticsChannelInjectionLoader(
     (): DiagnosticsChannelInjection => ({
-      integrations: [mysqlChannelIntegration(), postgresChannelIntegration(options.postgres)],
-      replacedOtelIntegrationNames: ['Mysql', 'Postgres'],
+      // Keyed by the OTel integration name each one replaces.
+      integrationFactories: {
+        Mysql: mysqlChannelIntegration,
+        Postgres: postgresChannelIntegration,
+      },
       register: registerDiagnosticsChannelInjection,
       detect: detectOrchestrionSetup,
     }),

packages/node/src/sdk/index.ts

@@ -30,32 +30,16 @@ export function getDefaultIntegrationsWithoutPerformance(): Integration[] {
 
 /** Get the default integrations for the Node SDK. */
 export function getDefaultIntegrations(options: Options): Integration[] {
-  const integrations: Integration[] = [
+  return [
     ...getDefaultIntegrationsWithoutPerformance(),
     // We only add performance integrations if tracing is enabled
-    // Note that this means that without tracing enabled, e.g. `expressIntegration()` will not be added
-    // This means that generally request isolation will work (because that is done by httpIntegration)
+    // Note that this means that without tracing enabled, e.g.
+    // `expressIntegration()` will not be added
+    // This means that generally request isolation will work (because that is
+    // done by httpIntegration)
     // But `transactionName` will not be set automatically
     ...(hasSpansEnabled(options) ? getAutoPerformanceIntegrations() : []),
   ];
-
-  // When the app opted into diagnostics-channel injection (via
-  // `experimentalUseDiagnosticsChannelInjection()`) AND span recording is
-  // enabled, swap the channel-based integrations in place of OTel equivalents
-  // so the two don't both instrument the same library.
-  //
-  // Every channel-based integration we ship today is a 1:1 replacement for an
-  // OTel performance/tracing integration and produces nothing but spans (those
-  // only come from `getAutoPerformanceIntegrations()` above), so it's gated on
-  // span recording.
-  if (isDiagnosticsChannelInjectionEnabled() && hasSpansEnabled(options)) {
-    const diagnosticsChannelInjection = resolveDiagnosticsChannelInjection();
-    if (diagnosticsChannelInjection) {
-      const replaced = new Set(diagnosticsChannelInjection.replacedOtelIntegrationNames);
-      return [...integrations.filter(i => !replaced.has(i.name)), ...diagnosticsChannelInjection.integrations];
-    }
-  }
-  return integrations;
 }
 
 /**

packages/node/test/sdk/orchestrionIntegrationSwap.test.ts

@@ -0,0 +1,71 @@
+import type { Integration } from '@sentry/core';
+import { afterEach, describe, expect, it, vi } from 'vitest';
+import { mysqlIntegration } from '../../src/integrations/tracing/mysql';
+import { postgresIntegration } from '../../src/integrations/tracing/postgres';
+import {
+  _resetDiagnosticsChannelInjectionForTesting,
+  setDiagnosticsChannelInjectionLoader,
+} from '../../src/sdk/diagnosticsChannelInjection';
+
+// `experimentalUseDiagnosticsChannelInjection()` registers
+// channel-integration factories into a runtime registry; the OTel
+// `xxxIntegration()` factories look themselves up there and build the
+// channel implementation instead. We exercise that swap by registering fakes
+// directly, so this file never imports the orchestrion code (which is exactly
+// the property that keeps it tree-shakeable).
+
+afterEach(() => {
+  _resetDiagnosticsChannelInjectionForTesting();
+  vi.restoreAllMocks();
+});
+
+describe('OTel integration factory <-> channel swap', () => {
+  it('returns the OTel implementation when injection is not opted into', () => {
+    // No loader registered (the default), so no channel factory is found and
+    // the factories build their own OTel implementation.
+    const pg = postgresIntegration();
+    const mysql = mysqlIntegration();
+
+    expect(pg.name).toBe('Postgres');
+    expect(typeof pg.setupOnce).toBe('function');
+    expect(mysql.name).toBe('Mysql');
+    expect(typeof mysql.setupOnce).toBe('function');
+  });
+
+  it('builds the registered channel implementation, forwarding options, when opted in', () => {
+    const pgChannel: Integration = { name: 'Postgres', setupOnce: vi.fn() };
+    const mysqlChannel: Integration = { name: 'Mysql', setupOnce: vi.fn() };
+    const pgFactory = vi.fn(() => pgChannel);
+    const mysqlFactory = vi.fn(() => mysqlChannel);
+
+    setDiagnosticsChannelInjectionLoader(() => ({
+      integrationFactories: { Postgres: pgFactory, Mysql: mysqlFactory },
+      register: vi.fn(),
+      detect: vi.fn(),
+    }));
+
+    const pg = postgresIntegration({ ignoreConnectSpans: true });
+    const mysql = mysqlIntegration();
+
+    // The factory's instance is returned verbatim
+    expect(pg).toBe(pgChannel);
+    expect(mysql).toBe(mysqlChannel);
+    // The user's options reach the channel factory unchanged.
+    expect(pgFactory).toHaveBeenCalledWith({ ignoreConnectSpans: true });
+  });
+
+  it('only swaps the integrations that have a registered factory', () => {
+    const pgChannel: Integration = { name: 'Postgres', setupOnce: vi.fn() };
+
+    setDiagnosticsChannelInjectionLoader(() => ({
+      integrationFactories: { Postgres: () => pgChannel },
+      register: vi.fn(),
+      detect: vi.fn(),
+    }));
+
+    // Postgres has a registered factory; mysql does not, so it stays OTel.
+    expect(postgresIntegration()).toBe(pgChannel);
+    expect(mysqlIntegration().name).toBe('Mysql');
+    expect(mysqlIntegration()).not.toBe(pgChannel);
+  });
+});