instrumentation.js

The instrumentation.js|ts file is used to integrate observability tools into your application, allowing you to track the performance and behavior, and to debug issues in production.

To use it, place the file in the root of your application or inside a src folder if using one.

Enabling Instrumentation

Instrumentation is currently an experimental feature, to use the instrumentation.js file, you must explicitly opt-in by defining experimental.instrumentationHook = true; in your next.config.js:

import type { NextConfig } from 'next'

const nextConfig: NextConfig = {
  experimental: {
    instrumentationHook: true,
  },
}

export default nextConfig

/** @type {import('next').NextConfig} */
const nextConfig = {
  experimental: {
    instrumentationHook: true,
  },
}

module.exports = nextConfig

Exports

register (required)

The file exports a register function that is called once when a new Next.js server instance is initiated. register can be an async function.

import { registerOTel } from '@vercel/otel'

export function register() {
  registerOTel('next-app')
}

import { registerOTel } from '@vercel/otel'

export function register() {
  registerOTel('next-app')
}

onRequestError (optional)

This API is available in Next.js canary.

You can optionally export an onRequestError function to track and send server errors to an observability tool.

import { type Instrumentation } from 'next'

export const onRequestError: Instrumentation.onRequestError = (
  err,
  request,
  context
) => {
  fetch('https://.../write-log', {
    method: 'POST',
    body: JSON.stringify({
      message: err.message,
      request,
      context,
    }),
    headers: {
      'Content-Type': 'application/json',
    },
  })
}

export function onRequestError(err, request, context) {
  fetch('https://.../write-log', {
    method: 'POST',
    body: JSON.stringify({
      message: err.message,
      request,
      context,
    }),
    headers: {
      'Content-Type': 'application/json',
    },
  })
}

Parameters

The function accepts three parameters: error, request, and context.

export function onRequestError(
  error: { digest: string } & Error,
  request: {
    path: string // resource path, e.g. /blog?name=foo
    method: string // request method. e.g. GET, POST, etc
    headers: { [key: string]: string }
  },
  context: {
    routerKind: 'Pages Router' | 'App Router' // the router type
    routePath: string // the route file path, e.g. /app/blog/[dynamic]
    routeType: 'render' | 'route' | 'action' | 'middleware' // the context in which the error occurred
    renderSource:
      | 'react-server-components'
      | 'react-server-components-payload'
      | 'server-rendering'
    revalidateReason: 'on-demand' | 'stale' | undefined // undefined is a normal request without revalidation
    renderType: 'dynamic' | 'dynamic-resume' // 'dynamic-resume' for PPR
  }
)

• error: The caught error itself (type is always Error), and a digest property which is the unique ID of the error.
• request: Read-only request information associated with the error.
• context: The context in which the error occurred. This can be the type of router (App or Pages Router), and/or (Server Components ('render'), Route Handlers ('route'), Server Actions ('action'), or Middleware ('middleware')).

Version History

Version	Changes
v15.0.0	onRequestError introduced
v14.0.4	Turbopack support for instrumentation
v13.2.0	instrumentation introduced as an experimental feature