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
Step 1. Install OpenTelemetry packages
npm install @vercel/otel @opentelemetry/api
Step 2. Update next.config.mjs to include instrumentationHook
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
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 3. Create instrumentation.js file
const { registerOTel, OTLPHttpJsonTraceExporter } = require('@vercel/otel');
// Add otel logging
const { diag, DiagConsoleLogger, DiagLogLevel } = require('@opentelemetry/api');
diag.setLogger(new DiagConsoleLogger(), DiagLogLevel.ERROR); // set diaglog level to DEBUG when debugging
exports.register = function() {
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.
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.
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
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:
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 3. Create instrumentation.js:
const { registerOTel, OTLPHttpJsonTraceExporter } = require('@vercel/otel');
// Add otel logging
const { diag, DiagConsoleLogger, DiagLogLevel } = require('@opentelemetry/api');
diag.setLogger(new DiagConsoleLogger(), DiagLogLevel.ERROR); // set diaglog level to DEBUG when debugging
exports.register = function() {
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.
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.
You can auto-instrument sending traces from Nextjs application using one of the following methods:
- Using Kubernetes OTel Operator (recommended)
- Using OTel Collector Agent
K8s OTel Operator Based Automatic Instrumentation (recommended)
Send traces directly to SigNoz Cloud - Using K8s OTel Operator
For Nextjs application deployed on Kubernetes, you can auto-instrument the traces using Kubernetes OpenTelemetry Operator.
An OpenTelemetry Operator is a Kubernetes Operator that manages OpenTelemetry Collectors and auto-instrumentation of workloads. It basically simplifies the deployment and management of OpenTelemetry in a Kubernetes environment.
The OpenTelemetry Operator provides two Custom Resource Definitions (CRDs):
OpenTelemetryCollectorInstrumentation
The OpenTelemetryCollector CRD allows you to deploy and manage OpenTelemetry Collectors in your Kubernetes cluster.
The Instrumentation CRD allows you to configure and inject OpenTelemetry auto-instrumentation libraries into your workloads.
Here are the steps you need to follow to auto-instrument Nextjs application using OTel Operator:
Step 1. Install cert-manager
Run the following commands to apply cert manager.
kubectl apply -f https://github.com/cert-manager/cert-manager/releases/download/v1.16.1/cert-manager.yaml
kubectl wait --for=condition=Available deployments/cert-manager -n cert-manager
Step 2. Install OpenTelemetry Operator
To install the operator in the existing K8s cluster, run the following command:
kubectl apply -f https://github.com/open-telemetry/opentelemetry-operator/releases/download/v0.116.0/opentelemetry-operator.yaml
Installing the OpenTelemetry Operator sets up the necessary components and configurations to enable the observability and monitoring of applications running in the cluster.
Step 3. Setup the OpenTelemetry Collector instance
Once the opentelemetry-operator has been deployed, you can proceed with the creation of the OpenTelemetry Collector (otelcol) instance. The OpenTelemetry Collector collects, processes, and exports telemetry data.
There are different deployment modes for the OpenTelemetryCollector, and you can specify them in the spec.mode section of the custom resource. The available deployment modes are:
- Daemonset
- Sidecar
- StatefulSet
- Deployment (default mode)
The default method - the Deployment mode, will be used here.
To create a simple instance of the OpenTelemetry Collector, create a file otel-collector.yaml with the following contents:
apiVersion: opentelemetry.io/v1alpha1
kind: OpenTelemetryCollector
metadata:
name: otel-collector
spec:
mode: deployment
config: |
receivers:
otlp:
protocols:
grpc:
endpoint: 0.0.0.0:4317
http:
endpoint: 0.0.0.0:4318
processors:
batch: {}
resource/env:
attributes:
- key: deployment.environment
value: prod # can be dev, prod, staging etc. based on your environment
action: upsert
exporters:
debug: {}
otlp:
endpoint: "ingest.<region>.signoz.cloud:443" # replace <region> with your region of SigNoz Cloud
tls:
insecure: false
headers:
"signoz-ingestion-key": "<your-ingestion-key>" # Obtain from https://{your-signoz-tenant-url}/settings/ingestion-settings
service:
pipelines:
traces:
receivers: [otlp]
processors: [batch, resource/env]
exporters: [otlp]
- Set the
<region>to match your SigNoz Cloud region - Replace
<your-ingestion-key>with your SigNoz ingestion key
Apply the above yaml file using the following command:
kubectl apply -f otel-collector.yaml
Step 4. Setup the Instrumentation instance
Once the OpenTelemetry Collector instance has been deployed, the next step will be to create an instrumentation instance, which will be responsible for sending OTLP data to the OTel Collector.
Create a file instrumentation.yaml with the following contents:
apiVersion: opentelemetry.io/v1alpha1
kind: Instrumentation
metadata:
name: traces-instrumentation
spec:
exporter:
endpoint: https://ingest.<region>.signoz.cloud:443 # replace <region> with your region of SigNoz Cloud
env:
- name: OTEL_EXPORTER_OTLP_HEADERS
value: signoz-ingestion-key="<signoz-token>" # Obtain from https://{your-signoz-url}/settings/ingestion-settings
- name: OTEL_EXPORTER_OTLP_INSECURE
value: "false"
propagators:
- tracecontext
- baggage
- b3
sampler:
type: parentbased_traceidratio
argument: "1"
nodejs:
image: ghcr.io/open-telemetry/opentelemetry-operator/autoinstrumentation-nodejs:latest
Apply the above instrumentation using the following command:
kubectl apply -f instrumentation.yaml
Step 5. Auto-instrument your Nextjs app with OpenTelemetry
Create deployment.yaml file for your Nextjs application as follows:
apiVersion: apps/v1
kind: Deployment
metadata:
name: nextjs-app
spec:
selector:
matchLabels:
app: nextjs-app
replicas: 1
template:
metadata:
labels:
app: nextjs-app
annotations:
instrumentation.opentelemetry.io/inject-nodejs: "true"
resource.opentelemetry.io/service.name: "nextjs-app"
spec:
containers:
- name: app
image: nextjs-app:latest
ports:
- containerPort: 8080
It is important to add the following annotation under spec > template > metadata > annotations:
instrumentation.opentelemetry.io/inject-nodejs: "true"`
This helps in auto-instrumenting the traces from the Nextjs application.
Apply the deployment using the following command:
kubectl apply -f deployment.yaml
With this, the auto-instrumentation of traces for Nextjs application is ready.
Step 6. Running the Nextjs application
In order to run the application on port 8080, run the following commands:
export POD_NAME=$(kubectl get pod -l app=<service-name> -o jsonpath="{.items[0].metadata.name}") # service name is `nextjs-app` in this case.
kubectl port-forward ${POD_NAME} 8080:8080
You can now access the application on port 8080.
You can validate if your application is sending traces to SigNoz cloud here.
In case you encounter an issue where all applications do not get listed in the services section then please refer to the troubleshooting section.
For Nextjs application deployed on Kubernetes, you need to install OTel Collector agent in your k8s infra to collect and send traces to SigNoz Cloud. You can find the instructions to install OTel Collector agent here.
Once you have set up OTel Collector agent, you can proceed with OpenTelemetry Javascript instrumentation by following either of the two:
Step 1. Install OpenTelemetry packages
npm install @vercel/otel @opentelemetry/api
Step 2. Update next.config.mjs to include instrumentationHook
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:
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 3. Create instrumentation.js:
const { registerOTel, OTLPHttpJsonTraceExporter } = require('@vercel/otel');
// Add otel logging
const { diag, DiagConsoleLogger, DiagLogLevel } = require('@opentelemetry/api');
diag.setLogger(new DiagConsoleLogger(), DiagLogLevel.ERROR); // set diaglog level to DEBUG when debugging
exports.register = function() {
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.
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.
In case you encounter an issue where all applications do not get listed in the services section then please refer to the troubleshooting section.
From Windows, there are two ways to send data to SigNoz Cloud.
Send traces directly to SigNoz Cloud from Windows
Step 1. Install OpenTelemetry packages
npm install @vercel/otel @opentelemetry/api
Step 2. Update next.config.mjs to include instrumentationHook
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
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 3. Create instrumentation.js file
const { registerOTel, OTLPHttpJsonTraceExporter } = require('@vercel/otel');
// Add otel logging
const { diag, DiagConsoleLogger, DiagLogLevel } = require('@opentelemetry/api');
diag.setLogger(new DiagConsoleLogger(), DiagLogLevel.ERROR); // set diaglog level to DEBUG when debugging
exports.register = function() {
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.
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 from Windows
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.
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
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:
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 3. Create instrumentation.js:
const { registerOTel, OTLPHttpJsonTraceExporter } = require('@vercel/otel');
// Add otel logging
const { diag, DiagConsoleLogger, DiagLogLevel } = require('@opentelemetry/api');
diag.setLogger(new DiagConsoleLogger(), DiagLogLevel.ERROR); // set diaglog level to DEBUG when debugging
exports.register = function() {
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.
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 to SigNoz Self-Host
If you're trying to send instrumentation data to SigNoz self-hosted way, the only minor thing (apart from installing OpenTelemetry packages) that you'd be required is to change the url and headers in the trace exporter
Step 1. Install OpenTelemetry packages
npm install @vercel/otel @opentelemetry/api
Step 2. Update next.config.mjs to include instrumentationHook
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:
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 3. Create instrumentation.js:
const { registerOTel, OTLPHttpJsonTraceExporter } = require('@vercel/otel');
// Add otel logging
const { diag, DiagConsoleLogger, DiagLogLevel } = require('@opentelemetry/api');
diag.setLogger(new DiagConsoleLogger(), DiagLogLevel.ERROR); // set diaglog level to DEBUG when debugging
exports.register = function() {
registerOTel({
serviceName: '<service_name>',
traceExporter: new OTLPHttpJsonTraceExporter({
url: 'http://localhost:4318/v1/traces',
}),
});
}
Step 5. Once you're done configuring the exporter options, try running your application and validate if your application is sending traces to SigNoz cloud here.
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
Servicestab. Hit theRefreshbutton on the top right corner, and your application should appear in the list ofApplications. - Go to the
Tracestab, 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
