Send OpenTelemetry from Next.js to your Mac

Next.js has OpenTelemetry support built in. One file and two environment variables send its traces to Loggerhead. One more package sends its metrics too.

Before you start

• Loggerhead is open.
• You know the effective port. Open Collectors → Loggerhead receiver → Connection and copy the HTTP port. The first workspace uses 4318. See Ports and the effective port.

Step 1: install the package

npm install @vercel/otel @opentelemetry/api

Step 2: add instrumentation.ts

Save this file as instrumentation.ts in the root of the project, beside app/. Next.js loads it before anything else.

instrumentation.ts

import { registerOTel } from '@vercel/otel';

export function register() {
  registerOTel({ serviceName: 'my-next-app' });
}

Next.js 14 and older

Next.js 15 loads the file by itself. On 13 and 14, add experimental: { instrumentationHook: true } to next.config.js.

Step 3: set the endpoint

.env.local

OTEL_EXPORTER_OTLP_ENDPOINT=http://127.0.0.1:4318
OTEL_EXPORTER_OTLP_PROTOCOL=http/protobuf

Start the app with npm run dev and open a page that reads data.

Step 4: send metrics too

registerOTel exports traces only. Give it a metric reader, and the counters and histograms that your code records with the OpenTelemetry API go to Loggerhead as well.

npm install @opentelemetry/sdk-metrics @opentelemetry/exporter-metrics-otlp-proto

instrumentation.ts

import { registerOTel } from '@vercel/otel';
import { OTLPMetricExporter } from '@opentelemetry/exporter-metrics-otlp-proto';
import { PeriodicExportingMetricReader } from '@opentelemetry/sdk-metrics';

export function register() {
  registerOTel({
    serviceName: 'my-next-app',
    metricReaders: [
      new PeriodicExportingMetricReader({ exporter: new OTLPMetricExporter(), exportIntervalMillis: 10_000 }),
    ],
  });
}

The exporter reads the same OTEL_EXPORTER_OTLP_ENDPOINT.

What arrives

Signal	State
Traces	Every request, with the render and the fetch calls inside it.
Metrics	Only with the metric reader of step 4: the metrics your code records. Next.js and @vercel/otel record none by themselves.
Logs	Not from this package. Send them through a branch collector, or add an OTLP log exporter.

Tag the environment

A record with no tag lands in the Local environment. To send a deployment somewhere else, name it:

OTEL_RESOURCE_ATTRIBUTES=deployment.environment.name=staging

See Workspaces and environments.

Then read it with your agent

1. Open Logs or Traces in Loggerhead. New records arrive while the page is live.
2. Connect your coding agent once, and it reads the same data. See Claude Code.