Next.js Instrumentation

Next.js provides an instrumentation.ts file that runs once when the server starts — before any request is handled. This is the ideal place to initialize observability.

registerVestig() turns that single file into a complete instrumentation setup: OTLP export, automatic fetch instrumentation, console capture, and database configuration — all in one call.

1import { registerVestig } from '@vestig/next/instrumentation'

Quick Start

1. Create instrumentation.ts

Add the file to your project root (next to next.config.ts):

1// instrumentation.ts
2import { registerVestig } from '@vestig/next/instrumentation'
3 
4export function register() {
5  registerVestig({
6    serviceName: 'my-app',
7  })
8}

2. Set environment variables

1OTEL_EXPORTER_OTLP_ENDPOINT=https://otel.example.com/v1/traces
2OTEL_EXPORTER_OTLP_HEADERS=Authorization=Bearer your-token

3. Start your app

OTLP export and fetch instrumentation are now active. Every outgoing fetch() call is traced automatically, and spans are exported to your configured endpoint.

RegisterVestigOptions

Top-level options passed to registerVestig():

OTLPConfig

Controls how spans are exported to your observability backend:

AutoInstrumentConfig

Controls what gets automatically instrumented at startup:

RegisterVestigResult

registerVestig() returns an object describing what was enabled:

1interface RegisterVestigResult {
2  /** Whether OTLP export was enabled */
3  otlpEnabled: boolean
4 
5  /** Whether fetch was instrumented */
6  fetchInstrumented: boolean
7 
8  /** Whether console capture was enabled */
9  consoleInstrumented: boolean
10 
11  /** Whether database instrumentation config was set */
12  databaseConfigured: boolean
13 
14  /** Shutdown function to flush pending spans and cleanup */
15  shutdown: () => Promise<void>
16}

Use the result to verify initialization or trigger a graceful shutdown.

Full Configuration Example

A complete setup with all available options:

1// instrumentation.ts
2import { registerVestig } from '@vestig/next/instrumentation'
3 
4export function register() {
5  const result = registerVestig({
6    serviceName: 'my-app',
7    otlp: {
8      endpoint: process.env.OTEL_EXPORTER_OTLP_ENDPOINT,
9      headers: {
10        'Authorization': `Bearer ${process.env.OTEL_AUTH_TOKEN}`,
11      },
12      serviceVersion: '1.0.0',
13      environment: process.env.VERCEL_ENV,
14      resourceAttributes: {
15        'cloud.region': 'us-east-1',
16      },
17      batchSize: 100,
18      flushInterval: 5000,
19    },
20    autoInstrument: {
21      fetch: {
22        captureHeaders: ['content-type', 'x-request-id'],
23        ignoreUrls: ['/health', /^\/_next/],
24      },
25      console: true,
26      database: {
27        slowQueryThreshold: 100,
28      },
29    },
30    debug: process.env.NODE_ENV === 'development',
31  })
32 
33  console.log('Vestig initialized:', {
34    otlp: result.otlpEnabled,
35    fetch: result.fetchInstrumented,
36  })
37}

Environment Variables

registerVestig() auto-reads several environment variables when the corresponding option is not explicitly set in config:

• OTEL_EXPORTER_OTLP_ENDPOINT -- OTLP traces endpoint. If missing and no otlp.endpoint is provided, OTLP export is skipped.
• OTEL_EXPORTER_OTLP_HEADERS -- Comma-separated key=value pairs for authentication headers. Merged with any otlp.headers you set in code (code takes precedence).
• VERCEL_ENV -- Deployment environment on Vercel (production, preview, or development). Used as the default for otlp.environment.
• NODE_ENV -- Fallback environment when VERCEL_ENV is not set.

Header format

The OTEL_EXPORTER_OTLP_HEADERS variable uses comma-separated key-value pairs:

1OTEL_EXPORTER_OTLP_HEADERS=Authorization=Bearer your-token,X-Custom=value

Values containing = are handled correctly -- only the first = is treated as the separator.

Vercel Deployment

Vercel has built-in support for OpenTelemetry. When you enable Observability in your Vercel project settings, Vercel provides an OTLP endpoint automatically.

To connect Vestig:

1. Enable Observability in your Vercel project dashboard
2. Set OTEL_EXPORTER_OTLP_ENDPOINT in your project environment variables
3. VERCEL_ENV is set automatically by Vercel to production, preview, or development
4. The endpoint auto-appends /v1/traces if missing -- you can provide the base URL or the full path

1// instrumentation.ts
2import { registerVestig } from '@vestig/next/instrumentation'
3 
4export function register() {
5  registerVestig({
6    serviceName: 'my-app',
7    // No otlp config needed — reads from env vars
8  })
9}

No additional configuration is required. registerVestig() reads OTEL_EXPORTER_OTLP_ENDPOINT and VERCEL_ENV from the environment automatically.

Debug Mode

Enable debug mode during development to see exactly what was initialized:

1registerVestig({
2  serviceName: 'my-app',
3  debug: process.env.NODE_ENV === 'development',
4})

When enabled, registerVestig() logs initialization status to the console:

1[vestig] Initializing for my-app...
2[vestig] OTLP enabled: https://otel.example.com/v1/traces
3[vestig] Fetch instrumentation enabled
4[vestig] Database instrumentation configured
5[vestig]   Slow query threshold: 100ms
6[vestig] Console capture enabled
7[vestig] Initialization complete

This helps verify that your endpoint is correctly resolved and all expected instrumentations are active.

Graceful Shutdown

The shutdown() function flushes any pending spans and cleans up resources. Use it to ensure no data is lost when your process exits:

1export function register() {
2  const { shutdown } = registerVestig({ serviceName: 'my-app' })
3 
4  process.on('SIGTERM', async () => {
5    await shutdown()
6    process.exit(0)
7  })
8}

shutdown() performs three things in order:

1. Restores console.error if console capture was enabled
2. Clears the global database configuration
3. Flushes all pending spans via the span processor pipeline

Next Steps

• OTLP Export — Configure backends like Jaeger, Honeycomb, Grafana Cloud
• Database Logging — Prisma, Drizzle, and PostgreSQL instrumentation
• Cloudflare & Edge — Edge runtime deployment guide
• Next.js Integration — Full overview of @vestig/next