feat(nextjs): Add opt-in for orchestrion instrumentation

dev-packages/e2e-tests/test-applications/node-exports-test-app/scripts/consistentExports.ts

@@ -29,6 +29,8 @@ const NODE_EXPORTS_IGNORE = [
   // factories for that same Node-runtime-only opt-in, so it isn't surfaced
   // through the framework / serverless SDKs either.
   'diagnosticsChannelInjectionIntegrations',
+  // Companion to the above two, same reasoning (Next.js re-exports it via `export * from '@sentry/node'`)
+  'isDiagnosticsChannelInjectionEnabled',
   // Internal helper only needed within integrations (e.g. bunRuntimeMetricsIntegration)
   '_INTERNAL_normalizeCollectionInterval',
 ];

packages/nextjs/package.json

@@ -85,6 +85,7 @@
     "@sentry/node": "10.65.0",
     "@sentry/opentelemetry": "10.65.0",
     "@sentry/react": "10.65.0",
+    "@sentry/server-utils": "10.65.0",
     "@sentry/vercel-edge": "10.65.0",
     "@sentry/webpack-plugin": "^5.3.0",
     "rollup": "^4.60.3",

packages/nextjs/src/config/diagnosticsChannelInjection.ts

@@ -0,0 +1,22 @@
+/**
+ * Instrumented packages verified (via e2e) to bundle correctly, removed from Sentry's own
+ * `serverExternalPackages` defaults so the build-time loader can transform them. Everything else
+ * stays external and is instrumented by the runtime module hook instead. Deliberately an
+ * allowlist — bundling can break packages outright (e.g. `mysql` 2.x under Turbopack).
+ */
+export const BUNDLE_SAFE_INSTRUMENTED_PACKAGES = ['ioredis'];
+
+/**
+ * The orchestrion runtime machinery must stay external — its parser breaks when bundled, which
+ * silently disables the runtime module hook.
+ */
+export const ORCHESTRION_RUNTIME_EXTERNAL_PACKAGES = [
+  '@apm-js-collab/tracing-hooks',
+  '@apm-js-collab/code-transformer',
+];
+
+/** Remove the given packages from a `serverExternalPackages` list. */
+export function filterInstrumentedExternals(externals: string[], packagesToBundle: string[]): string[] {
+  const set = new Set(packagesToBundle);
+  return externals.filter(name => !set.has(name));
+}

packages/nextjs/src/config/turbopack/constructTurbopackConfig.ts

@@ -1,8 +1,15 @@
 import { debug } from '@sentry/core';
 import * as path from 'path';
+import { getOrchestrionLoaderPath, getSentryInstrumentations } from '@sentry/server-utils/orchestrion/webpack';
 import type { VercelCronsConfig } from '../../common/types';
 import type { RouteManifest } from '../manifest/types';
-import type { NextConfigObject, SentryBuildOptions, TurbopackMatcherWithRule, TurbopackOptions } from '../types';
+import type {
+  JSONValue,
+  NextConfigObject,
+  SentryBuildOptions,
+  TurbopackMatcherWithRule,
+  TurbopackOptions,
+} from '../types';
 import { supportsNativeDebugIds, supportsTurbopackRuleCondition } from '../util';
 import { generateValueInjectionRules } from './generateValueInjectionRules';
 
@@ -106,9 +113,42 @@ export function constructTurbopackConfig({
     });
   }
 
+  newConfig.rules = maybeAddOrchestrionRule(newConfig.rules, userSentryOptions, nextJsVersion);
+
   return newConfig;
 }
 
+/**
+ * Adds the orchestrion code-transform loader rule when diagnostics-channel injection is enabled.
+ */
+function maybeAddOrchestrionRule(
+  rules: TurbopackOptions['rules'],
+  userSentryOptions: SentryBuildOptions | undefined,
+  nextJsVersion: string | undefined,
+): TurbopackOptions['rules'] {
+  if (
+    !userSentryOptions?._experimental?.useDiagnosticsChannelInjection ||
+    !nextJsVersion ||
+    !supportsTurbopackRuleCondition(nextJsVersion)
+  ) {
+    return rules;
+  }
+
+  return safelyAddTurbopackRule(rules, {
+    matcher: '*.{js,mjs,cjs}',
+    rule: {
+      condition: 'node',
+      loaders: [
+        {
+          loader: getOrchestrionLoaderPath(),
+          // `instrumentations` is JSON-serializable
+          options: { instrumentations: getSentryInstrumentations() as unknown as JSONValue[] },
+        },
+      ],
+    },
+  });
+}
+
 /**
  * Safely add a Turbopack rule to the existing rules.
  *

packages/nextjs/src/config/types.ts

@@ -10,7 +10,7 @@ type NextRewrite = {
   destination: string;
 };
 
-interface WebpackPluginInstance {
+export interface WebpackPluginInstance {
   [index: string]: unknown;
   apply: (compiler: unknown) => void;
 }
@@ -765,6 +765,19 @@ export type SentryBuildOptions = {
       enabled?: boolean;
       ignoredComponents?: string[];
     };
+    /**
+     * EXPERIMENTAL: Wire up orchestrion diagnostics-channel instrumentation at build time.
+     *
+     * When enabled, `withSentryConfig` injects the orchestrion code-transform loader for bundled
+     * server packages and keeps the remaining instrumented packages external so the runtime module
+     * hook picks them up. You must still call `Sentry.experimentalUseDiagnosticsChannelInjection()`
+     * in your server config to record spans.
+     *
+     * Turbopack support requires Next.js 16+; the webpack path works on earlier versions.
+     *
+     * @experimental May change or be removed in any release.
+     */
+    useDiagnosticsChannelInjection?: boolean;
   }>;
 
   /**

packages/nextjs/src/config/webpack.ts

@@ -20,7 +20,9 @@ import type {
   WebpackConfigObject,
   WebpackConfigObjectWithModuleRules,
   WebpackEntryProperty,
+  WebpackPluginInstance,
 } from './types';
+import { sentryOrchestrionWebpackPlugin } from '@sentry/server-utils/orchestrion/webpack';
 import { getNextjsVersion, getPackageModules } from './util';
 import type { VercelCronsConfigResult } from './withSentryConfig/getFinalConfigObjectUtils';
 
@@ -429,6 +431,11 @@ export function constructWebpackConfigFunction({
       }),
     );
 
+    // Orchestrion code-transform loader — Node server runtime only, never the edge compilation
+    if (runtime === 'server' && userSentryOptions._experimental?.useDiagnosticsChannelInjection) {
+      newConfig.plugins.push(sentryOrchestrionWebpackPlugin() as WebpackPluginInstance);
+    }
+
     return newConfig;
   };
 }

packages/nextjs/src/config/withSentryConfig/buildTime.ts

@@ -1,6 +1,7 @@
 import * as childProcess from 'child_process';
 import * as fs from 'fs';
 import * as path from 'path';
+import { getTracingHooksDirectory } from '@sentry/server-utils/orchestrion/webpack';
 import type { NextConfigObject, SentryBuildOptions } from '../types';
 
 /**
@@ -50,6 +51,14 @@ export function setUpBuildTimeVariables(
     buildTimeVariables._sentryRewritesTunnelPath = rewritesTunnelPath;
   }
 
+  // Marker read by the server SDK to warn if the runtime opt-in call is missing.
+  if (userSentryOptions._experimental?.useDiagnosticsChannelInjection) {
+    buildTimeVariables._sentryUseDiagnosticsChannelInjection = 'true';
+    // Resolved here (where the SDK is a real on-disk package) and inlined, because the runtime
+    // module hook can't resolve the bare specifier from a bundled server chunk under pnpm.
+    buildTimeVariables._sentryOrchestrionTracingHooksDir = getTracingHooksDirectory();
+  }
+
   if (basePath) {
     buildTimeVariables._sentryBasePath = basePath;
   }

packages/nextjs/src/config/withSentryConfig/getFinalConfigObject.ts

@@ -85,9 +85,11 @@ export function getFinalConfigObject(
 
   maybeEnableTurbopackSourcemaps(incomingUserNextConfigObject, userSentryOptions, bundlerInfo);
 
+  const useDiagnosticsChannelInjection = userSentryOptions._experimental?.useDiagnosticsChannelInjection ?? false;
+
   return {
     ...incomingUserNextConfigObject,
-    ...getServerExternalPackagesPatch(incomingUserNextConfigObject, nextMajor),
+    ...getServerExternalPackagesPatch(incomingUserNextConfigObject, nextMajor, useDiagnosticsChannelInjection),
     ...getWebpackPatch({
       incomingUserNextConfigObject,
       userSentryOptions,

packages/nextjs/src/config/withSentryConfig/getFinalConfigObjectBundlerUtils.ts

@@ -1,3 +1,8 @@
+import {
+  BUNDLE_SAFE_INSTRUMENTED_PACKAGES,
+  filterInstrumentedExternals,
+  ORCHESTRION_RUNTIME_EXTERNAL_PACKAGES,
+} from '../diagnosticsChannelInjection';
 import { handleRunAfterProductionCompile } from '../handleRunAfterProductionCompile';
 import type { RouteManifest } from '../manifest/types';
 import { constructTurbopackConfig } from '../turbopack';
@@ -227,23 +232,32 @@ export function maybeEnableTurbopackSourcemaps(
 export function getServerExternalPackagesPatch(
   incomingUserNextConfigObject: NextConfigObject,
   nextMajor: number | undefined,
+  useDiagnosticsChannelInjection = false,
 ): Partial<NextConfigObject> {
+  // Diagnostics-channel injection: only bundle-safe packages leave OUR defaults (→ build-time
+  // loader); everything else stays external (→ runtime module hook), including the orchestrion
+  // machinery itself, which breaks when bundled.
+  const mergeExternals = (userProvided: string[] | undefined): string[] => {
+    const defaults = useDiagnosticsChannelInjection
+      ? filterInstrumentedExternals(DEFAULT_SERVER_EXTERNAL_PACKAGES, BUNDLE_SAFE_INSTRUMENTED_PACKAGES)
+      : DEFAULT_SERVER_EXTERNAL_PACKAGES;
+    return [
+      ...(userProvided || []),
+      ...defaults,
+      ...(useDiagnosticsChannelInjection ? ORCHESTRION_RUNTIME_EXTERNAL_PACKAGES : []),
+    ];
+  };
+
   if (nextMajor && nextMajor >= 15) {
-    return {
-      serverExternalPackages: [
-        ...(incomingUserNextConfigObject.serverExternalPackages || []),
-        ...DEFAULT_SERVER_EXTERNAL_PACKAGES,
-      ],
-    };
+    return { serverExternalPackages: mergeExternals(incomingUserNextConfigObject.serverExternalPackages) };
   }
 
   return {
     experimental: {
       ...incomingUserNextConfigObject.experimental,
-      serverComponentsExternalPackages: [
-        ...(incomingUserNextConfigObject.experimental?.serverComponentsExternalPackages || []),
-        ...DEFAULT_SERVER_EXTERNAL_PACKAGES,
-      ],
+      serverComponentsExternalPackages: mergeExternals(
+        incomingUserNextConfigObject.experimental?.serverComponentsExternalPackages,
+      ),
     },
   };
 }

packages/nextjs/src/server/index.ts

@@ -12,7 +12,13 @@ import {
   SEMANTIC_ATTRIBUTE_SENTRY_OP,
 } from '@sentry/core';
 import type { NodeClient, NodeOptions } from '@sentry/node';
-import { getDefaultIntegrations, httpIntegration, init as nodeInit } from '@sentry/node';
+import {
+  experimentalUseDiagnosticsChannelInjection as nodeExperimentalUseDiagnosticsChannelInjection,
+  getDefaultIntegrations,
+  httpIntegration,
+  init as nodeInit,
+  isDiagnosticsChannelInjectionEnabled,
+} from '@sentry/node';
 import { DEBUG_BUILD } from '../common/debug-build';
 import { devErrorSymbolicationEventProcessor } from '../common/devErrorSymbolicationEventProcessor';
 import { getVercelEnv } from '../common/getVercelEnv';
@@ -41,8 +47,26 @@ export { startSpan, startSpanManual, startInactiveSpan } from '../common/utils/n
 const globalWithInjectedValues = GLOBAL_OBJ as typeof GLOBAL_OBJ & {
   _sentryRewriteFramesDistDir?: string;
   _sentryRelease?: string;
+  _sentryUseDiagnosticsChannelInjection?: string;
+  _sentryOrchestrionTracingHooksDir?: string;
 };
 
+/**
+ * EXPERIMENTAL: Next.js-aware variant of `Sentry.experimentalUseDiagnosticsChannelInjection()`
+ * from `@sentry/node` (see its docs for behavior and caveats).
+ *
+ * Next.js bundles the SDK into the server build, from where the runtime module hook can't resolve
+ * the `@apm-js-collab/tracing-hooks` bare specifier under isolated installs (pnpm). This variant
+ * points the hook at the package location that `withSentryConfig` resolved at build time.
+ *
+ * @experimental May change or be removed in any release.
+ */
+export function experimentalUseDiagnosticsChannelInjection(): void {
+  const tracingHooksDir =
+    process.env._sentryOrchestrionTracingHooksDir || globalWithInjectedValues._sentryOrchestrionTracingHooksDir;
+  nodeExperimentalUseDiagnosticsChannelInjection(tracingHooksDir ? { tracingHooksDir } : undefined);
+}
+
 // Call at module level so `next build` prerender workers still register the runner without `init`
 prepareSafeIdGeneratorContext();
 
@@ -138,6 +162,17 @@ export function init(options: NodeOptions): NodeClient | undefined {
     customDefaultIntegrations.push(distDirRewriteFramesIntegration({ distDirName }));
   }
 
+  // The build wired the orchestrion loader but the runtime opt-in is missing → no DB spans.
+  const useDiagnosticsChannelInjection =
+    process.env._sentryUseDiagnosticsChannelInjection || globalWithInjectedValues._sentryUseDiagnosticsChannelInjection;
+  if (DEBUG_BUILD && useDiagnosticsChannelInjection && !isDiagnosticsChannelInjectionEnabled()) {
+    debug.warn(
+      '[@sentry/nextjs] `useDiagnosticsChannelInjection` is enabled in `withSentryConfig`, but ' +
+        '`Sentry.experimentalUseDiagnosticsChannelInjection()` was not called before `Sentry.init()`. ' +
+        'Server DB spans will not be recorded.',
+    );
+  }
+
   // Detect if running on OpenNext/Cloudflare and get runtime config
   const cloudflareConfig = getCloudflareRuntimeConfig();
 

packages/nextjs/test/config/diagnosticsChannelInjection.test.ts

@@ -0,0 +1,73 @@
+import { describe, expect, it } from 'vitest';
+import {
+  BUNDLE_SAFE_INSTRUMENTED_PACKAGES,
+  filterInstrumentedExternals,
+} from '../../src/config/diagnosticsChannelInjection';
+import { setUpBuildTimeVariables } from '../../src/config/withSentryConfig/buildTime';
+import { getServerExternalPackagesPatch } from '../../src/config/withSentryConfig/getFinalConfigObjectBundlerUtils';
+import type { NextConfigObject } from '../../src/config/types';
+
+describe('filterInstrumentedExternals', () => {
+  it('removes the given packages, keeps the rest', () => {
+    expect(
+      filterInstrumentedExternals(['express', 'pg', 'pg-pool', 'ioredis', 'mongodb'], ['pg', 'pg-pool', 'ioredis']),
+    ).toEqual(['express', 'mongodb']);
+  });
+
+  it('is a no-op with an empty bundle list', () => {
+    expect(filterInstrumentedExternals(['express', 'pg'], [])).toEqual(['express', 'pg']);
+  });
+});
+
+describe('getServerExternalPackagesPatch (diagnostics-channel injection)', () => {
+  it('keeps everything external except the bundle-safe allowlist, and adds the runtime machinery', () => {
+    const patch = getServerExternalPackagesPatch({}, 16, true);
+    const externals = patch.serverExternalPackages ?? [];
+
+    // Only the verified bundle-safe packages leave the external list (→ build-time loader).
+    for (const name of BUNDLE_SAFE_INSTRUMENTED_PACKAGES) {
+      expect(externals).not.toContain(name);
+    }
+    // Other instrumented packages stay external (→ runtime module hook).
+    expect(externals).toContain('mysql');
+    expect(externals).toContain('pg');
+    expect(externals).toContain('pg-pool');
+    // The orchestrion machinery must be external for the runtime hook to work.
+    expect(externals).toContain('@apm-js-collab/tracing-hooks');
+    expect(externals).toContain('@apm-js-collab/code-transformer');
+  });
+
+  it('respects user-provided externals even for bundle-safe packages', () => {
+    const patch = getServerExternalPackagesPatch({ serverExternalPackages: ['ioredis'] }, 16, true);
+    expect(patch.serverExternalPackages).toContain('ioredis');
+  });
+
+  it('is unchanged with the flag off', () => {
+    const patch = getServerExternalPackagesPatch({}, 16, false);
+    const externals = patch.serverExternalPackages ?? [];
+    expect(externals).toContain('ioredis');
+    expect(externals).toContain('mysql');
+    expect(externals).not.toContain('@apm-js-collab/tracing-hooks');
+  });
+});
+
+describe('setUpBuildTimeVariables (diagnostics-channel injection)', () => {
+  it('injects the flag marker and the tracing-hooks location', () => {
+    const nextConfig: NextConfigObject = {};
+    setUpBuildTimeVariables(nextConfig, { _experimental: { useDiagnosticsChannelInjection: true } }, undefined);
+
+    expect(nextConfig.env).toMatchObject({
+      _sentryUseDiagnosticsChannelInjection: 'true',
+      // The runtime module hook joins subpaths onto this, so it must be an absolute directory.
+      _sentryOrchestrionTracingHooksDir: expect.stringMatching(/@apm-js-collab[/+]tracing-hooks/),
+    });
+  });
+
+  it('injects neither with the flag off', () => {
+    const nextConfig: NextConfigObject = {};
+    setUpBuildTimeVariables(nextConfig, {}, undefined);
+
+    expect(nextConfig.env).not.toHaveProperty('_sentryUseDiagnosticsChannelInjection');
+    expect(nextConfig.env).not.toHaveProperty('_sentryOrchestrionTracingHooksDir');
+  });
+});