OpenTelemetry in Next.js 16 — Silent Route Handler Failures Masked a 15% Error Rate

Next.js 16’s server components are a black box by default — errors thrown inside them are caught by the framework, logged to the server console, and silently converted to a generic 500 response. Unless you’re actively watching server logs, these errors are invisible. We discovered this the hard way: a 15% error rate in our API route handlers went undetected for three weeks because none of our monitoring tools were instrumented to capture server-side Next.js errors.

The fix was implementing OpenTelemetry (OTEL) instrumentation via Next.js’s instrumentation.ts file, configuring exporters to send traces to our observability platform (Grafana Tempo), and adding custom spans for database queries, external API calls, and render operations. This single change turned a “deployment looks fine” team into one that could see every millisecond of every request.

This guide covers: setting up instrumentation.ts, tracing server components and route handlers, using the after() API for post-response logging, configuring the OpenTelemetry SDK for Next.js, and building dashboards that show real-time error rates, latency distributions, and dependency health across your entire application.

What instrumentation.ts Actually Does — The Node.js Bootstrap Hook

Next.js 16 loads instrumentation.ts from your project root at server startup, before the application code begins executing. This is the critical timing: you must register OpenTelemetry SDK, configure exporters, and load instrumentations BEFORE any application modules are imported. If you register OTEL after a module has been loaded, that module’s operations will not be instrumented.

The file exports a single register() function that Next.js calls during initialization. Inside this function, you configure the Node.js SDK, set up the span processor and exporter, register auto-instrumentation packages, and optionally initialize custom tracer instances. The file lives at the project root (next to next.config.js), not inside the app/ directory.

We initially placed instrumentation.ts inside app/ and wondered why no spans appeared. Next.js only loads this file from the project root. Placement matters because Node.js module resolution determines import timing.

export async function register() {
  if (process.env.NEXT_RUNTIME === 'edge') return;

  const { NodeSDK } = await import('@opentelemetry/sdk-node');
  const { OTLPTraceExporter } = await import('@opentelemetry/exporter-trace-otlp-proto');
  const { HttpInstrumentation } = await import('@opentelemetry/instrumentation-http');
  const { PgInstrumentation } = await import('@opentelemetry/instrumentation-pg');

  const sdk = new NodeSDK({
    traceExporter: new OTLPTraceExporter({
      url: process.env.OTEL_EXPORTER_OTLP_ENDPOINT || 'http://localhost:4318/v1/traces',
    }),
    instrumentations: [
      new HttpInstrumentation(),
      new PgInstrumentation(),
    ],
  });

  sdk.start();

  process.on('SIGTERM', () => {
    sdk.shutdown().catch(console.error);
  });
}

Auto-Instrumentation vs Custom Spans — What Each Captures

Auto-instrumentation packages (@opentelemetry/instrumentation-http, -express, -pg, -grpc, etc.) automatically wrap library functions to create spans without any code changes. They capture: HTTP request duration, status codes, and headers; database query text and duration; gRPC call metadata; and outgoing fetch/axios requests.

But auto-instrumentation cannot capture business-level spans: “user authentication duration,” “payment processing,” “AI response generation.” For these, you need custom spans created via trace.getTracer().startSpan(). The power of OpenTelemetry is combining auto-instrumentation (infrastructure layer) with custom spans (application layer) in a single trace waterfall.

We realized that auto-instrumentation alone was insufficient: it showed us that a route handler returned 500 after 8 seconds but not which sub-operation (payment gateway call) caused the failure. Adding custom spans around the payment gateway call revealed that the Stripe API call was taking 7.5 seconds due to a network routing issue.

import { trace, SpanStatusCode } from '@opentelemetry/api';

const tracer = trace.getTracer('my-app');

export async function tracedFetch<T>(
  name: string,
  url: string,
  options?: RequestInit
): Promise<T> {
  return tracer.startActiveSpan(name, async (span) => {
    span.setAttribute('http.url', url);
    try {
      const response = await fetch(url, options);
      span.setAttribute('http.status_code', response.status);
      if (!response.ok) {
        span.setStatus({ code: SpanStatusCode.ERROR, message: response.statusText });
      }
      return response.json() as Promise<T>;
    } catch (error) {
      span.setStatus({ code: SpanStatusCode.ERROR, message: String(error) });
      throw error;
    } finally {
      span.end();
    }
  });
}

The after() API — Post-Response Logging Without Blocking the Response

The after() function from next/server schedules a callback to execute after the response has been sent to the client. This is the perfect mechanism for non-critical post-response work: logging, metrics submission, cache warmup, and cleanup operations. The callback runs in the same request context but does not increase the response latency visible to the user.

Critically, after() callbacks maintain the OpenTelemetry trace context from the parent request. This means spans created inside after() are correctly parented to the original request trace. You can log errors, submit custom metrics, or perform cleanup without worrying about slowing down the user-facing response.

We use after() for: submitting page-level performance metrics to our analytics pipeline, logging slow database queries (>500ms) for offline analysis, warming caches for related pages after a content update, and flushing OpenTelemetry batch spans to ensure they’re exported before the process terminates.

import { after } from 'next/server';

export default async function Page() {
  const start = Date.now();
  const data = await fetchData();

  after(() => {
    const duration = Date.now() - start;
    if (duration > 500) {
      console.warn('Slow page render', { duration, path: '/' });
    }
    reportMetric('page.render.duration', duration);
  });

  return <div>{data}</div>;
}

useReportWebVitals — Client-Side Performance Meets OTEL Tracing

Next.js provides useReportWebVitals for capturing client-side performance metrics (LCP, CLS, INP, FCP, TTFB). These metrics are reported from the browser and are independent of server-side OpenTelemetry. The challenge: correlating client-side metrics with server-side traces.

The solution is to generate a unique trace ID on the server (via OpenTelemetry), pass it to the client as a data attribute, and include it when reporting web vitals. This connects the server-side span (request handling) with the client-side span (page rendering) in a single trace waterfall.

We implemented this by embedding the trace ID in the HTML response as a meta tag, reading it in useReportWebVitals, and including it as a custom dimension in the web vitals report. Our observability platform then shows: server took 200ms to generate HTML, browser took 2.3s to render LCP, and the database query that caused the server delay.

'use client';

import { useReportWebVitals } from 'next/web-vitals';

export function WebVitalsReporter() {
  useReportWebVitals((metric) => {
    const traceId =
      document.querySelector('meta[name="trace-id"]')?.getAttribute('content') || 'unknown';

    const body = {
      name: metric.name,
      value: metric.value,
      rating: metric.rating,
      traceId,
      path: window.location.pathname,
    };

    if (process.env.NODE_ENV === 'production') {
      navigator.sendBeacon('/api/vitals', JSON.stringify(body));
    } else {
      console.debug('Web Vitals:', body);
    }
  });

  return null;
}

The ‘Unhandled’ Error Trap — Why process.on(‘uncaughtException’) Is Dangerous

A common mistake when implementing Node.js error monitoring is adding a process.on(‘uncaughtException’) handler to log errors. This is dangerous because Node.js enters an unknown state after an uncaught exception — event loop ticks may fail, file descriptors may leak, and the process becomes unreliable. The Node.js documentation explicitly recommends against it.

Instead, use process.on(‘unhandledRejection’) for promise rejections, and rely on OpenTelemetry’s auto-instrumentation to capture exceptions within request contexts. For truly unexpected errors, let the process crash (honoring the container orchestrator’s restart policy) rather than trying to recover in an unstable state.

We learned this when a process.on(‘uncaughtException’) handler caught a socket hang-up error, logged it to our monitoring, and continued running. The process then failed to accept new connections for 5 minutes before the health check finally killed it.

process.on('unhandledRejection', (reason) => {
  console.error('Unhandled Rejection:', reason);
});

// DO NOT add uncaughtException handler
// Let the process crash and restart via orchestrator

OTEL Exporters — Choosing Between Batch, Simple, and Custom Span Processors

OpenTelemetry in Node.js offers several span processors and exporters. The BatchSpanProcessor buffers spans in memory and exports them in batches at configurable intervals (default 5 seconds). This is the most efficient for production: minimal overhead, configurable batch size, and built-in retry logic. The SimpleSpanProcessor exports each span immediately as it ends — higher overhead but lower latency for span visibility.

For Next.js server components, the BatchSpanProcessor is the right choice. Server components may create dozens of spans per request (layout, page, child components, data fetching). Batching reduces the export overhead from O(n) exports to O(1) batch exports per interval.

The critical configuration: set scheduledDelayMillis to a value that balances visibility latency with overhead. We use 2 seconds in production: spans appear in Grafana within 2-3 seconds of the request completing, with an overhead cost of less than 0.1% CPU.

import { BatchSpanProcessor } from '@opentelemetry/sdk-trace-base';

const processor = new BatchSpanProcessor(exporter, {
  scheduledDelayMillis: 2000,
  maxExportBatchSize: 512,
  maxQueueSize: 2048,
});

const sdk = new NodeSDK({
  spanProcessor: processor,
  instrumentations: [/* ... */],
});

Building a Server Error Dashboard — What Metrics Matter for Next.js

After implementing OTEL, building the right dashboard is critical. The metrics that caught the 15% error rate for us: HTTP error rate by route (not just overall), p50/p95/p99 latency per route, database query duration histogram, span status distribution (OK, ERROR, UNSET), and error count by span name.

For Next.js specifically, add: server component render duration (per component type), middleware execution duration, route handler invocation count, server action execution duration, and cache hit/miss ratio for unstable_cache invocations.

The dashboard that caught our silent errors: we filtered spans with status.code = ERROR grouped by http.route. This showed that /api/search had a 15% error rate while every other route was below 1%. The error was invisible in traditional APM because Next.js returned HTTP 200 for the page that included the search widget, and the widget’s inline error handling never propagated to the response code.

import { trace } from '@opentelemetry/api';

export function recordRouteMetrics(
  route: string,
  duration: number,
  status: 'ok' | 'error'
) {
  const meter = trace.getMeter('nextjs-metrics');
  const histogram = meter.createHistogram('http.server.duration', {
    unit: 'ms',
    description: 'HTTP server duration in milliseconds',
  });

  histogram.record(duration, {
    'http.route': route,
    'http.status': status,
  });
}

Server Actions and OpenTelemetry — Tracing Beyond HTTP

Server Actions in Next.js 16 are called via POST requests to /_next/... internal endpoints. Auto-instrumentation captures these as HTTP spans, but the span names are meaningless for debugging. You need to add custom attributes to identify which server action created each span.

The approach: create a custom wrapper around Server Actions that starts an active span with the action’s name as the span name. This overwrites the generic HTTP span name with something meaningful like server-action.submitContactForm. Add attributes for the action’s input parameters (sanitized to exclude PII), execution duration, and error details.

import { trace, SpanStatusCode } from '@opentelemetry/api';

const tracer = trace.getTracer('server-actions');

export function withTrace<T>(
  actionName: string,
  fn: () => Promise<T>
): Promise<T> {
  return tracer.startActiveSpan(`server-action.${actionName}`, async (span) => {
    span.setAttribute('action.name', actionName);
    try {
      const result = await fn();
      span.setStatus({ code: SpanStatusCode.OK });
      return result;
    } catch (error) {
      span.setStatus({
        code: SpanStatusCode.ERROR,
        message: error instanceof Error ? error.message : String(error),
      });
      throw error;
    } finally {
      span.end();
    }
  });
}

REPL Summary — The 3 Commands That Diagnose Any Monitoring Gap

When you suspect silent errors are slipping through your monitoring, these three checks will reveal the gaps:

1. kubectl logs --since=24h | grep -c ‘Error’ — if this returns a non-zero number but your dashboard shows 0 errors, you have a monitoring gap.
2. curl -s http://localhost:3000/api/health && curl -s http://localhost:9464/metrics | grep ‘http_server_duration_count’ — compares request count from your app vs metric count.
3. NODE_OPTIONS=’--require @opentelemetry/auto-instrumentations-node/register’ node server.js — runs your server with auto-instrumentation on demand to verify OTEL works before committing changes.

#!/bin/bash
echo "=== Checking Error Monitoring Gap ==="

echo -n "Errors in last 24h logs: "
kubectl logs --since=24h -l app=nextjs | grep -c 'Error' 2>/dev/null || echo "(no logs available)"

echo -n "Dashboard reported errors "
curl -sf http://localhost:9464/metrics | grep 'http_server_duration_count' 2>/dev/null || echo "(metrics endpoint not configured)"

echo -e "\nIf log errors > dashboard errors, your OTEL pipeline is missing captures."
echo "Install OTEL instrumentation and verify spans appear in your backend."

OpenTelemetry Collector — Why You Need It and How to Configure It

The OpenTelemetry Collector is a vendor-agnostic agent that receives, processes, and exports telemetry data. In a Next.js deployment, running a collector as a sidecar has three benefits: it handles batching and retry logic (offloading work from your Node.js process), it provides a local endpoint that stays constant regardless of backend changes, and it transforms data (e.g., redacting PII, adding cluster metadata).

Deploy the collector as a sidecar container in your Kubernetes pod or as a separate container in your Docker Compose setup. The Node.js process sends spans to localhost:4318 (OTLP HTTP), and the collector handles export to your backend (Grafana Tempo, Jaeger, Datadog, Honeycomb).

We initially sent spans directly from Next.js to Grafana Cloud, which created a tight coupling between our application and the backend. Switching to a local collector meant we could change backends without changing application code, and the collector’s batch processing reduced our span export overhead by another 40%.

receivers:
  otlp:
    protocols:
      http:
        endpoint: 0.0.0.0:4318

processors:
  batch:
    timeout: 1s
    send_batch_size: 1024
  memory_limiter:
    check_interval: 1s
    limit_mib: 512
  attributes:
    actions:
      - key: environment
        value: production
        action: upsert

exporters:
  otlp:
    endpoint: grafana-tempo.example.com:4317
    headers:
      Authorization: "Bearer ${TEMPO_API_KEY}"

service:
  pipelines:
    traces:
      receivers: [otlp]
      processors: [memory_limiter, attributes, batch]
      exporters: [otlp]