Nextjs OpenTelemetry Instrumentation

This document contains instructions on how to set up OpenTelemetry instrumentation in your Nextjs applications and view your application traces in SigNoz.

Send traces to SigNoz Cloud

Based on your application environment, you can choose the setup below to send traces to SigNoz Cloud.

From VMs, there are two ways to send data to SigNoz Cloud.

Send traces directly to SigNoz Cloud
Send traces via OTel Collector binary (recommended)

Send traces directly to SigNoz Cloud

Step 1. Install OpenTelemetry packages

npm install @vercel/otel @opentelemetry/api

Step 2. Update next.config.mjs to include instrumentationHook

📝 Note

This step is only needed when using NextJs 14 and below

/** @type {import('next').NextConfig} */
const nextConfig = {
    // include instrumentationHook experimental feature
    experimental: {
        instrumentationHook: true,
    },
};

export default nextConfig;

Step 3. Create instrumentation.ts file

instrumentation.ts

import { registerOTel, OTLPHttpJsonTraceExporter } from '@vercel/otel';
// Add otel logging
import { diag, DiagConsoleLogger, DiagLogLevel } from '@opentelemetry/api';
diag.setLogger(new DiagConsoleLogger(), DiagLogLevel.ERROR); // set diaglog level to DEBUG when debugging
export function register() {
  registerOTel({
    serviceName: '<service_name>',
    traceExporter: new OTLPHttpJsonTraceExporter({
        url: 'https://ingest.<region>.signoz.cloud:443/v1/traces',
        headers: { 'signoz-ingestion-key': '<your-ingestion-key>' },
    }),
  });
}

<service_name> is name of your service
Set the <region> to match your SigNoz Cloud region
Replace <your-ingestion-key> with your SigNoz ingestion key

Step 4. Once you're done configuring the exporter options, try running your application and validate if your application is sending traces to SigNoz cloud here.

📝 Note

The instrumentation file should be in the root of your project and not inside the app or pages directory. If you're using the src folder, then place the file inside src alongside pages and app.

You can also check the sample application at this GitHub repo.

Send traces via OTel Collector binary

OTel Collector binary helps to collect logs, hostmetrics, resource and infra attributes. It is recommended to install Otel Collector binary to collect and send traces to SigNoz cloud. You can correlate signals and have rich contextual data through this way.

📝 Note

You can find instructions to install OTel Collector binary here in your VM. Once you are done setting up your OTel Collector binary, you can follow the below steps for instrumenting your Javascript application.

Step 1. Install OpenTelemetry packages

npm install @vercel/otel @opentelemetry/api

Step 2. Update next.config.mjs to include instrumentationHook

📝 Note

This step is only needed when using NextJs 14 and below

/** @type {import('next').NextConfig} */
const nextConfig = {
    // include instrumentationHook experimental feature
    experimental: {
        instrumentationHook: true,
    },
};

export default nextConfig;

Step 3. Create instrumentation.ts:

instrumentation.ts

import { registerOTel, OTLPHttpJsonTraceExporter } from '@vercel/otel';
// Add otel logging
import { diag, DiagConsoleLogger, DiagLogLevel } from '@opentelemetry/api';
diag.setLogger(new DiagConsoleLogger(), DiagLogLevel.ERROR); // set diaglog level to DEBUG when debugging

export function register() {
  registerOTel({
    serviceName: '<service_name>',
    traceExporter: new OTLPHttpJsonTraceExporter({
        url: 'http://localhost:4318/v1/traces',
    }),
  });
}

<service_name> is name of your service

Step 4. Once you're done configuring the exporter options, try running your application and validate if your application is sending traces to SigNoz cloud here.

📝 Note

The instrumentation file should be in the root of your project and not inside the app or pages directory. If you're using the src folder, then place the file inside src alongside pages and app.

You can also check the sample application at this GitHub repo.

Validating instrumentation by checking for traces

With your application running, you can verify that you’ve instrumented your application with OpenTelemetry correctly by confirming that tracing data is being reported to SigNoz.

To do this, you need to ensure that your application generates some data. Applications will not produce traces unless they are being interacted with, and OpenTelemetry will often buffer data before sending. So you need to interact with your application and wait for some time to see your tracing data in SigNoz.

Validate your traces in SigNoz:

Trigger an action in your app that generates a web request. Hit the endpoint a number of times to generate some data. Then, wait for some time.
In SigNoz, open the Services tab. Hit the Refresh button on the top right corner, and your application should appear in the list of Applications.
Go to the Traces tab, and apply relevant filters to see your application’s traces.

If you face any issues while trying out SigNoz, you can reach out with your questions in #support channel 👇

Further Reading

Implementing OpenTelemetry in Angular application

Monitor your Nodejs application with OpenTelemetry and SigNoz