Next.js

Choose the server-side instrumentation for your Next.js deployment:

Self-hosted, Node.js runtime: use the ClickStack Node.js SDK.
Vercel or the Edge runtime: use @vercel/otel.

For browser telemetry and session replay, use the Browser SDK guide.

Self-hosted Next.js

Use Node.js 22.15 or later and install the SDK:

npm install @clickhouse/clickstack-node

Create instrumentation.ts in your project root, or in src if your application uses that directory. Initialize the SDK only in the Node.js runtime:

export async function register() {
  if (process.env.NEXT_RUNTIME === 'nodejs') {
    const { init } = await import('@clickhouse/clickstack-node');
    init();
  }
}

Add the SDK to serverExternalPackages in your existing Next.js configuration so it is loaded outside the server bundle:

// next.config.mjs
export default {
  serverExternalPackages: ['@clickhouse/clickstack-node'],
};

Configure the destination below and set OTEL_SERVICE_NAME to identify your application. Do not also preload the SDK or initialize another OpenTelemetry SDK. For additional options, see the Node.js guide. For termination and deployment considerations, see the SDK’s Next.js guidance.

Vercel and Edge runtime

Use @vercel/otel following the Next.js OpenTelemetry setup instructions. Use this setup instead of the ClickStack Node.js SDK initialization above. Configure OTLP export using the connection settings below. Replace any example destinations and signal-specific endpoint overrides, and set the variables in your deployment configuration. If your Vercel deployment already uses a tracing integration, configure a custom exporter for this destination; endpoint environment variables alone do not override that integration.

Configure your destination

Set a service name for either instrumentation option:

export OTEL_SERVICE_NAME='my-nextjs-app'

Fully managed
Self-managed

Open Team Settings → Data → Managed Telemetry in your service and copy the OTLP HTTP endpoint and API key. Use the complete HTTPS endpoint, including its port:

export OTEL_EXPORTER_OTLP_ENDPOINT='https://YOUR_OTEL_ENDPOINT:4318'
export OTEL_EXPORTER_OTLP_HEADERS='authorization=Bearer%20YOUR_INGESTION_API_KEY'
export OTEL_EXPORTER_OTLP_PROTOCOL='http/protobuf'

Use your collector’s OTLP HTTP endpoint and ingestion key. Use http:// instead of https:// if your collector does not have TLS configured. For collector setup, see Ingesting with OpenTelemetry.

export OTEL_EXPORTER_OTLP_ENDPOINT='https://YOUR_COLLECTOR_HOST:4318'
export OTEL_EXPORTER_OTLP_HEADERS='authorization=YOUR_INGESTION_API_KEY'
export OTEL_EXPORTER_OTLP_PROTOCOL='http/protobuf'

Verify ingestion

Start your application and make requests to a server-rendered page or API route. In ClickHouse Observability, select a recent time range and find your application’s service name in Traces.

Introduction

Features

Administration

Guides

Integration partners

Self-managed

Self-hosted Next.js

Vercel and Edge runtime

Configure your destination

Verify ingestion

​Self-hosted Next.js

​Vercel and Edge runtime

​Configure your destination

​Verify ingestion

Self-hosted Next.js

Vercel and Edge runtime

Configure your destination

Verify ingestion