How to Implement instrumentation.js in a next.js project

Question

Accepted Answer

// instrumentation.js or instrumentation.ts
// Place this file in your project root directory (or src folder)

// Register function is called once when the server starts
export function register() {
  console.log('Instrumentation registered - server starting');
  // Initialize monitoring tools here
}

// Optional: Handle server errors (Next.js 15+)
export function onRequestError(error, request, context) {
  console.error('Server error:', error.message);
  // Send to your error tracking service
  // await fetch('https://your-monitoring-service.com/error', { ... });
} **Create the instrumentation file:** Place instrumentation.js|ts in your project's root directory (or inside src folder if using one) - not inside app or pages directories **Export a register function:** This function is called once when the Next.js server instance is initiated and can be async **For Next.js 14 or earlier:** Enable experimental flag in next.config.js with experimental.instrumentationHook = true **Use environment-specific code:** Check process.env.NEXT_RUNTIME to conditionally import code for Node.js vs Edge runtime **Import side-effect modules:** Use await import() inside the register function for packages with side effects rather than importing at the top of the file For production use, a common implementation pattern is integrating OpenTelemetry for observability. The @vercel/otel package provides a streamlined way to add OpenTelemetry instrumentation to your Next.js application. You can also create custom instrumentation for browser-side monitoring by conditionally initializing telemetry in your app component when running on the client side. // instrumentation.ts
import { registerOTel } from '@vercel/otel';

export function register() {
  // Initialize OpenTelemetry with your service name
  registerOTel('my-nextjs-app');
  
  // Import runtime-specific instrumentation
  if (process.env.NEXT_RUNTIME === 'nodejs') {
    // Node.js specific instrumentation
    import('./instrumentation-node');
  }
  
  if (process.env.NEXT_RUNTIME === 'edge') {
    // Edge runtime specific instrumentation
    import('./instrumentation-edge');
  }
} // instrumentation.ts
import { type Instrumentation } from 'next';

export const onRequestError: Instrumentation.onRequestError = async (
  error,
  request,
  context
) => {
  // Send error details to your monitoring service
  await fetch('https://api.monitoring-service.com/track', {
    method: 'POST',
    body: JSON.stringify({
      error: {
        message: error.message,
        digest: error.digest, // Unique error ID
        stack: error.stack
      },
      request: {
        path: request.path,
        method: request.method,
        headers: request.headers
      },
      context: {
        routerKind: context.routerKind, // 'Pages Router' or 'App Router'
        routePath: context.routePath,
        routeType: context.routeType // 'render', 'route', 'action', or 'middleware'
      }
    }),
    headers: { 'Content-Type': 'application/json' }
  });
};

How to Implement instrumentation.js in a next.js project

How to Implement instrumentation.js in a next.js project

Scenario Questions

Follow-up Questions