Stablize instrumentation.js (#68853)

### What

- After adding a new API `onRequestError()` and a few fixes on `register()` for `instrumentation.js`, it's time to promote it as stable API.
- Add warning `"experimental.instrumentationHook is no longer needed to be configured in Next.js"` when you configure a `instrumentationHook` option in next.config.js

Related PRs
#67539, #67671, #67703, #67848, #67859, #67856, #67805, #68616, #68672, #68764, #68845 #68976, #68983

Closes NDX-89

packages/next/src/build/index.ts

@@ -862,15 +862,9 @@ export default async function build(
       )
 
       const rootDir = path.join((pagesDir || appDir)!, '..')
-      const instrumentationHookEnabled = Boolean(
-        config.experimental.instrumentationHook
-      )
-
       const includes = [
         middlewareDetectionRegExp,
-        ...(instrumentationHookEnabled
-          ? [instrumentationHookDetectionRegExp]
-          : []),
+        instrumentationHookDetectionRegExp,
       ]
 
       const rootPaths = Array.from(await getFilesInDir(rootDir))
@@ -1351,7 +1345,6 @@ export default async function build(
           currentEntrypoints,
           currentEntryIssues,
           manifestLoader,
-          nextConfig: config,
           devRewrites: undefined,
           productionRewrites: customRoutes.rewrites,
           logErrors: false,

packages/next/src/server/config-schema.ts

@@ -394,7 +394,6 @@ export const configSchema: zod.ZodType<NextConfig> = z.lazy(() =>
           .optional(),
         optimizePackageImports: z.array(z.string()).optional(),
         optimizeServerReact: z.boolean().optional(),
-        instrumentationHook: z.boolean().optional(),
         clientTraceMetadata: z.array(z.string()).optional(),
         turbotrace: z
           .object({

packages/next/src/server/config-shared.ts

@@ -407,11 +407,6 @@ export interface ExperimentalConfig {
    */
   webpackMemoryOptimizations?: boolean
 
-  /**
-   *
-   */
-  instrumentationHook?: boolean
-
   /**
    * The array of the meta tags to the client injected by tracing propagation data.
    */
@@ -1036,7 +1031,6 @@ export const defaultConfig: NextConfig = {
     turbotrace: undefined,
     typedRoutes: false,
     typedEnv: false,
-    instrumentationHook: false,
     clientTraceMetadata: undefined,
     parallelServerCompiles: false,
     parallelServerBuildTraces: false,

packages/next/src/server/config.ts

@@ -471,6 +471,13 @@ function assignDefaults(
     silent
   )
 
+  warnOptionHasBeenDeprecated(
+    result,
+    'experimental.instrumentationHook',
+    '`experimental.instrumentationHook` is no longer needed to be configured in Next.js',
+    silent
+  )
+
   warnOptionHasBeenMovedOutOfExperimental(
     result,
     'bundlePagesExternals',

packages/next/src/server/dev/hot-reloader-turbopack.ts

@@ -478,7 +478,6 @@ export async function createHotReloaderTurbopack(
 
         currentEntryIssues,
         manifestLoader,
-        nextConfig: opts.nextConfig,
         devRewrites: opts.fsChecker.rewrites,
         productionRewrites: undefined,
         logErrors: true,

packages/next/src/server/dev/turbopack-utils.ts

@@ -709,7 +709,6 @@ export async function handleEntrypoints({
 
   currentEntryIssues,
   manifestLoader,
-  nextConfig,
   devRewrites,
   productionRewrites,
   logErrors,
@@ -721,7 +720,6 @@ export async function handleEntrypoints({
 
   currentEntryIssues: EntryIssuesMap
   manifestLoader: TurbopackManifestLoader
-  nextConfig: NextConfigComplete
   devRewrites: SetupOpts['fsChecker']['rewrites'] | undefined
   productionRewrites: CustomRoutes['rewrites'] | undefined
   logErrors: boolean
@@ -793,7 +791,7 @@ export async function handleEntrypoints({
 
   currentEntrypoints.global.middleware = middleware
 
-  if (nextConfig.experimental.instrumentationHook && instrumentation) {
+  if (instrumentation) {
     const processInstrumentation = async (
       name: string,
       prop: 'nodeJs' | 'edge'

packages/next/src/server/lib/router-utils/setup-dev-bundler.ts

@@ -396,10 +396,7 @@ async function startWatcher(opts: SetupOpts) {
           ]
           continue
         }
-        if (
-          isInstrumentationHookFile(rootFile) &&
-          nextConfig.experimental.instrumentationHook
-        ) {
+        if (isInstrumentationHookFile(rootFile)) {
           serverFields.actualInstrumentationHookFile = rootFile
           await propagateServerField(
             opts,

packages/next/src/server/next-server.ts

@@ -297,10 +297,7 @@ export default class NextNodeServer extends BaseServer<
   }
 
   protected async loadInstrumentationModule() {
-    if (
-      !this.serverOptions.dev &&
-      !!this.nextConfig.experimental.instrumentationHook
-    ) {
+    if (!this.serverOptions.dev) {
       try {
         this.instrumentation = await dynamicRequire(
           resolve(

test/e2e/app-dir/next-after-app/next.config.js

@@ -3,6 +3,5 @@ module.exports = {
   experimental: {
     after: true,
     testProxy: true,
-    instrumentationHook: true,
   },
 }

test/e2e/instrumentation-hook-src/instrumentation-hook-src.test.ts

@@ -4,11 +4,6 @@ describe('instrumentation-hook-rsc', () => {
   describe('instrumentation', () => {
     const { next, isNextDev, skipped } = nextTestSetup({
       files: __dirname,
-      nextConfig: {
-        experimental: {
-          instrumentationHook: true,
-        },
-      },
       skipDeployment: true,
     })
 

test/e2e/instrumentation-hook/flying-shuttle/next.config.js

@@ -6,6 +6,5 @@ module.exports = {
     flyingShuttle: {
       mode: 'full',
     },
-    instrumentationHook: true,
   },
 }

test/e2e/instrumentation-hook/general/next.config.js

@@ -1,5 +1 @@
-module.exports = {
-  experimental: {
-    instrumentationHook: true,
-  },
-}
+module.exports = {}

test/e2e/instrumentation-hook/instrumentation-hook.test.ts

@@ -17,33 +17,15 @@ const describeCase = (
   })
 }
 describe('Instrumentation Hook', () => {
-  // TODO: investigate the failure with esm import
-  // createNextDescribe(
-  //   'with-esm-import',
-  //   {
-  //     files: path.join(__dirname, 'with-esm-import'),
-  //     nextConfig: {
-  //       experimental: {
-  //         instrumentationHook: true,
-  //       },
-  //     },
-  //     dependencies: {
-  //       // This test is mostly for compatibility with this package
-  //       '@vercel/otel': 'latest',
-  //     },
-  //     skipDeployment: true,
-  //   },
-  //   ({ next }) => {
-  // eslint-disable-next-line jest/no-commented-out-tests
-  //     it('with-esm-import should run the instrumentation hook', async () => {
-  //       await next.render('/')
-  //       await check(
-  //         () => next.cliOutput,
-  //         /register in instrumentation\.js is running/
-  //       )
-  //     })
-  //   }
-  // )
+  describeCase('with-esm-import', ({ next }) => {
+    it('with-esm-import should run the instrumentation hook', async () => {
+      await next.render('/')
+      await check(
+        () => next.cliOutput,
+        /register in instrumentation\.js is running/
+      )
+    })
+  })
 
   describeCase('with-middleware', ({ next }) => {
     it('with-middleware should run the instrumentation hook', async () => {

test/e2e/instrumentation-hook/register-once/next.config.js

@@ -1,5 +1 @@
-module.exports = {
-  experimental: {
-    instrumentationHook: true,
-  },
-}
+module.exports = {}

test/e2e/instrumentation-hook/with-async-edge-page/next.config.js

@@ -1,5 +1 @@
-module.exports = {
-  experimental: {
-    instrumentationHook: true,
-  },
-}
+module.exports = {}

test/e2e/instrumentation-hook/with-async-node-page/next.config.js

@@ -1,5 +1 @@
-module.exports = {
-  experimental: {
-    instrumentationHook: true,
-  },
-}
+module.exports = {}

test/e2e/instrumentation-hook/with-edge-api/next.config.js

@@ -1,5 +1 @@
-module.exports = {
-  experimental: {
-    instrumentationHook: true,
-  },
-}
+module.exports = {}

test/e2e/instrumentation-hook/with-edge-page/next.config.js

@@ -1,5 +1 @@
-module.exports = {
-  experimental: {
-    instrumentationHook: true,
-  },
-}
+module.exports = {}

test/e2e/instrumentation-hook/with-esm-import/.gitignore

@@ -0,0 +1 @@
+!node_modules

test/e2e/instrumentation-hook/with-esm-import/instrumentation.js

@@ -1,7 +1,7 @@
-import * as otel from '@vercel/otel'
+import * as mod from 'my-lib'
 
 export function register() {
   console.log('register in instrumentation.js is running')
   // make sure that this is not tree-shaken
-  if (process.env.DOESNT_EXIST_1234) otel()
+  if (process.env.DOESNT_EXIST_1234) mod.c()
 }

test/e2e/instrumentation-hook/with-esm-import/next.config.js

@@ -1,5 +1 @@
-module.exports = {
-  experimental: {
-    instrumentationHook: true,
-  },
-}
+module.exports = {}

test/e2e/instrumentation-hook/with-middleware/next.config.js

@@ -1,5 +1 @@
-module.exports = {
-  experimental: {
-    instrumentationHook: true,
-  },
-}
+module.exports = {}

test/e2e/instrumentation-hook/with-node-api/next.config.js

@@ -1,5 +1 @@
-module.exports = {
-  experimental: {
-    instrumentationHook: true,
-  },
-}
+module.exports = {}

test/e2e/instrumentation-hook/with-node-page/next.config.js

@@ -1,5 +1 @@
-module.exports = {
-  experimental: {
-    instrumentationHook: true,
-  },
-}
+module.exports = {}

test/e2e/on-request-error/basic/next.config.js

@@ -1,5 +1 @@
-module.exports = {
-  experimental: {
-    instrumentationHook: true,
-  },
-}
+module.exports = {}

test/e2e/on-request-error/dynamic-routes/next.config.js

@@ -1,5 +1 @@
-module.exports = {
-  experimental: {
-    instrumentationHook: true,
-  },
-}
+module.exports = {}

test/e2e/on-request-error/isr/next.config.js

@@ -1,5 +1 @@
-module.exports = {
-  experimental: {
-    instrumentationHook: true,
-  },
-}
+module.exports = {}

test/e2e/on-request-error/server-action-error/next.config.js

@@ -1,5 +1 @@
-module.exports = {
-  experimental: {
-    instrumentationHook: true,
-  },
-}
+module.exports = {}

test/e2e/on-request-error/skip-next-internal-error/next.config.js

@@ -1,5 +1 @@
-module.exports = {
-  experimental: {
-    instrumentationHook: true,
-  },
-}
+module.exports = {}

test/e2e/opentelemetry/client-trace-metadata/next.config.js

@@ -1,6 +1,5 @@
 module.exports = {
   experimental: {
-    instrumentationHook: true,
     clientTraceMetadata: [
       'my-parent-span-id',
       'my-test-key-1',

test/e2e/opentelemetry/instrumentation/next.config.js

@@ -1,5 +1 @@
-module.exports = {
-  experimental: {
-    instrumentationHook: true,
-  },
-}
+module.exports = {}

test/e2e/opentelemetry/instrumentation/opentelemetry.test.ts

@@ -61,7 +61,7 @@ describe('opentelemetry', () => {
       },
     },
   ]) {
-    // turbopack does not support experimental.instrumentationHook
+    // turbopack does not support instrumentation.js
     ;(process.env.TURBOPACK || process.env.__NEXT_EXPERIMENTAL_PPR
       ? describe.skip
       : describe)(env.name, () => {
@@ -836,7 +836,7 @@ describe('opentelemetry with disabled fetch tracing', () => {
     await collector.shutdown()
   })
 
-  // turbopack does not support experimental.instrumentationHook
+  // turbopack does not support instrumentation.js
   ;(process.env.TURBOPACK || process.env.__NEXT_EXPERIMENTAL_PPR
     ? describe.skip
     : describe)('root context', () => {

test/e2e/rsc-layers-transform/next.config.js

@@ -1,5 +1 @@
-module.exports = {
-  experimental: {
-    instrumentationHook: true,
-  },
-}
+module.exports = {}

test/integration/config-experimental-warning/test/index.test.js

@@ -139,7 +139,7 @@ describe('Config Experimental Warning', () => {
           experimental: {
             workerThreads: true,
             scrollRestoration: true,
-            instrumentationHook: true,
+            parallelServerCompiles: true,
             cpus: 2,
           }
         }
@@ -162,7 +162,7 @@ describe('Config Experimental Warning', () => {
           experimental: {
             workerThreads: true,
             scrollRestoration: true,
-            instrumentationHook: true,
+            parallelServerCompiles: true,
             cpus: 2,
           }
         }
@@ -172,7 +172,7 @@ describe('Config Experimental Warning', () => {
         expect(stdout).toMatch(' · cpus')
         expect(stdout).toMatch(' · workerThreads')
         expect(stdout).toMatch(' · scrollRestoration')
-        expect(stdout).toMatch(' · instrumentationHook')
+        expect(stdout).toMatch(' · parallelServerCompiles')
       })
 
       it('should show unrecognized experimental features in warning but not in start log experiments section', async () => {

test/production/instrumentation/required-files-instrumentation-entry/next.config.js

@@ -1,6 +1,2 @@
 /** @type {import('next').NextConfig} */
-module.exports = {
-  experimental: {
-    instrumentationHook: true,
-  },
-}
+module.exports = {}