Next.js OpenTelemetry instrumentation

Next.js loads OpenTelemetry through its built-in instrumentation.ts hook rather than the --require flag used by other Node.js frameworks. Because Next.js bundles server code and runs some routes on the Edge runtime, the supported path is the @vercel/otel package, which configures the SDK for both runtimes and sends traces, metrics, and logs to Osuite over OTLP.

Fastest path. Run this in your AI IDE and the Instrumentation Agent wires this service up for you.

/osuite-instrument nextjs

Prefer to do it by hand? Follow the manual steps below — they are the complete path.

Prerequisites

• Next.js 15 or newer (App Router or Pages Router). On Next.js 13.4–14 the instrumentation hook is behind a flag — see the note below.
• Node.js 18 or newer.
• An Osuite ingest token from Settings → API Keys.

Instrument the app

1. Install the package

   npm install @vercel/otel

   @vercel/otel bundles the OpenTelemetry SDK and OTLP exporters, so no separate exporter packages are required.

2. Create the instrumentation hook

   Create instrumentation.ts in your project root (or inside src/ if you use a src directory). Next.js calls the exported register function once when the server starts.

   instrumentation.ts

   import { registerOTel } from '@vercel/otel';
   
   export function register() {
     registerOTel({ serviceName: 'storefront' });
   }

Configure and run

@vercel/otel reads the OTLP endpoint and headers from environment variables and defaults to the HTTP/protobuf transport:

• OTEL_EXPORTER_OTLP_ENDPOINT — your Osuite ingest endpoint.
• OTEL_EXPORTER_OTLP_HEADERS — the x-osuite-ingest-token header that authenticates ingestion.
• OTEL_SERVICE_NAME — the service name that identifies this service in Osuite. Set it to the same name passed as serviceName in the register call above (storefront); if the two disagree, your telemetry is split across two services in Osuite.
• OTEL_RESOURCE_ATTRIBUTES — additional resource attributes such as service.environment.

Build the app (npm run build) and start it. Choose your deployment target:

Bare host

export OTEL_EXPORTER_OTLP_ENDPOINT="https://ingest.<region>.osuite.io:443"
export OTEL_EXPORTER_OTLP_HEADERS="x-osuite-ingest-token=<your-ingest-token>"
export OTEL_SERVICE_NAME="storefront"
export OTEL_RESOURCE_ATTRIBUTES="service.environment=production"

npm run start

Docker

# Dockerfile
FROM node:22-slim
WORKDIR /app
COPY package*.json ./
RUN npm ci
COPY . .
RUN npm run build
CMD ["npm", "run", "start"]

Pass the configuration at run time so the ingest token never lands in the image:

docker run \
  -e OTEL_EXPORTER_OTLP_ENDPOINT="https://ingest.<region>.osuite.io:443" \
  -e OTEL_EXPORTER_OTLP_HEADERS="x-osuite-ingest-token=<your-ingest-token>" \
  -e OTEL_SERVICE_NAME="storefront" \
  -e OTEL_RESOURCE_ATTRIBUTES="service.environment=production" \
  storefront

Kubernetes

Store the ingest token in a Secret:

kubectl create secret generic osuite-ingest \
  --from-literal=otlp-headers="x-osuite-ingest-token=<your-ingest-token>"

Reference it from the Deployment:

apiVersion: apps/v1
kind: Deployment
metadata:
  name: storefront
spec:
  replicas: 1
  selector:
    matchLabels:
      app: storefront
  template:
    metadata:
      labels:
        app: storefront
    spec:
      containers:
        - name: storefront
          image: storefront:latest
          command: ["npm", "run", "start"]
          env:
            - name: OTEL_EXPORTER_OTLP_ENDPOINT
              value: "https://ingest.<region>.osuite.io:443"
            - name: OTEL_EXPORTER_OTLP_HEADERS
              valueFrom:
                secretKeyRef:
                  name: osuite-ingest
                  key: otlp-headers
            - name: OTEL_SERVICE_NAME
              value: "storefront"
            - name: OTEL_RESOURCE_ATTRIBUTES
              value: "service.environment=production"

Framework notes

Do not use --require with Next.js

Next.js bundles and transforms server code, so loading the SDK with node --require does not reliably patch the framework, and it fails outright on the Edge runtime. Always instrument through instrumentation.ts and @vercel/otel. A raw NodeSDK with getNodeAutoInstrumentations() is not supported inside the Next.js bundle.

Older Next.js versions

On Next.js 13.4 through 14 the hook is opt-in. Enable it in next.config.js:

next.config.js

module.exports = {
  experimental: { instrumentationHook: true },
};

From Next.js 15 the hook is stable and no config flag is needed.

Running your own NodeSDK

If you need a raw NodeSDK (for example, to add a custom span processor), guard it so it only runs on the Node.js runtime and never on the Edge runtime:

instrumentation.ts

export async function register() {
  if (process.env.NEXT_RUNTIME === 'nodejs') {
    await import('./instrumentation.node');
  }
}

Put the NodeSDK setup in instrumentation.node.ts. The NEXT_RUNTIME guard prevents the Node-only SDK from being pulled into an Edge bundle.

Verify in Osuite

What you should see

Load a page or call a route handler, then open APM. The storefront service appears within a minute, emitting request-rate and latency metrics. Opening a trace shows the inbound request span with child spans for server-side data fetches and outbound calls.

Troubleshooting

No data in Osuite after a few minutes? Work through these checks.

• Endpoint — confirm the exporter targets exactly ingest.<region>.osuite.io:443 for your region, over TLS.
• Token — confirm the ingest header carries a valid <your-ingest-token> and has not been rotated.
• Pipeline — confirm the signal you expect (traces, logs, or metrics) is wired into an active pipeline with the otlp/osuite exporter attached.
• Export errors — check the application or Collector logs for OTLP export failures (auth, DNS, TLS, connection refused).
• Network — confirm the host has outbound access to the ingest endpoint on port 443.
• Timing — allow up to a minute for the first data to appear before assuming a failure.

Still stuck? Ask the Investigation Agent or contact support.

For Node-specific issues — including why the instrumentation hook may not fire — see Node.js troubleshooting.

Next steps

• Add custom spans and metrics inside your route handlers and server actions.
• Instrument the browser with Real User Monitoring.
• Correlate application logs with traces.