Skip to main content
Skip to main content
Edit this page

Next.js

ClickStack can ingest native OpenTelemetry traces from your Next.js serverless functions in Next 13.2+.

This Guide Integrates:

  • Console Logs
  • Traces
Note

If you're looking for session replay/browser-side monitoring, you'll want to install the Browser integration instead.

Installing​

Enable instrumentation hook (required for v15 and below)​

To get started, you'll need to enable the Next.js instrumentation hook by setting experimental.instrumentationHook = true; in your next.config.js.

Example:

const nextConfig = {
  experimental: {
    instrumentationHook: true,
  },
  // Ignore otel pkgs warnings 
  // https://github.com/open-telemetry/opentelemetry-js/issues/4173#issuecomment-1822938936
  webpack: (
    config,
    { buildId, dev, isServer, defaultLoaders, nextRuntime, webpack },
  ) => {
    if (isServer) {
      config.ignoreWarnings = [{ module: /opentelemetry/ }];
    }
    return config;
  },
};

module.exports = nextConfig;

Install ClickHouse OpenTelemetry SDK​

npm install @hyperdx/node-opentelemetry

Create instrumentation files​

Create a file called instrumentation.ts (or .js) in your Next.js project root with the following contents:

export async function register() {
  if (process.env.NEXT_RUNTIME === 'nodejs') {
    const { init } = await import('@hyperdx/node-opentelemetry');
    init({
      apiKey: '<YOUR_INGESTION_API_KEY>', // optionally configure via `HYPERDX_API_KEY` env var
      service: '<MY_SERVICE_NAME>', // optionally configure via `OTEL_SERVICE_NAME` env var
      additionalInstrumentations: [], // optional, default: []
    });
  }
}

This will allow Next.js to import the OpenTelemetry instrumentation for any serverless function invocation.

Configure environment variables​

If you're sending traces directly to ClickStack, you'll need to start your Next.js server with the following environment variables to point spans towards the OTel collector:

HYPERDX_API_KEY=<YOUR_INGESTION_API_KEY> \
OTEL_SERVICE_NAME=<MY_SERVICE_NAME> \
OTEL_EXPORTER_OTLP_ENDPOINT=http://localhost:4318
npm run dev

If you're deploying in Vercel, ensure that all the environment variables above are configured for your deployment.