Nuxt.js OpenTelemetry Instrumentation

This guide shows you how to instrument your Nuxt.js application with OpenTelemetry and send traces to SigNoz. You can use either zero-code auto-instrumentation or code-level setup for more control.

Prerequisites

Node.js 18 or later
A Nuxt.js application (Nuxt 3 recommended)
A SigNoz Cloud account or self-hosted SigNoz instance

Send traces to SigNoz

Step 1. Set environment variables

export OTEL_TRACES_EXPORTER="otlp"
export OTEL_EXPORTER_OTLP_ENDPOINT="https://ingest.<region>.signoz.cloud:443"
export OTEL_NODE_RESOURCE_DETECTORS="env,host,os"
export OTEL_SERVICE_NAME="<service_name>"
export OTEL_EXPORTER_OTLP_HEADERS="signoz-ingestion-key=<your-ingestion-key>"
export NODE_OPTIONS="--require @opentelemetry/auto-instrumentations-node/register"

Replace the following:

<region>: Your SigNoz Cloud region (us, eu, or in). See endpoints.
<your-ingestion-key>: Your SigNoz ingestion key.
<service_name>: Name of your service.

Step 2. Install OpenTelemetry packages

npm install --save @opentelemetry/api @opentelemetry/auto-instrumentations-node

Step 3. Run the application

npm run dev

💡 Tip

Need to enable or disable instrumentation for specific libraries? Check out our guide on selective instrumentation.

Step 1. Set environment variables

Add these environment variables to your Kubernetes deployment manifest:

env:
- name: OTEL_TRACES_EXPORTER
  value: 'otlp'
- name: OTEL_EXPORTER_OTLP_ENDPOINT
  value: 'https://ingest.<region>.signoz.cloud:443'
- name: OTEL_NODE_RESOURCE_DETECTORS
  value: 'env,host,os'
- name: OTEL_SERVICE_NAME
  value: '<service-name>'
- name: OTEL_EXPORTER_OTLP_HEADERS
  value: 'signoz-ingestion-key=<your-ingestion-key>'
- name: NODE_OPTIONS
  value: '--require @opentelemetry/auto-instrumentations-node/register'

Replace the following:

<region>: Your SigNoz Cloud region (us, eu, or in). See endpoints.
<your-ingestion-key>: Your SigNoz ingestion key.
<service-name>: Name of your service.

Step 2. Install OpenTelemetry packages

Ensure your application includes the OpenTelemetry packages:

npm install --save @opentelemetry/api @opentelemetry/auto-instrumentations-node

Step 3. Deploy and run

Apply your deployment manifest to start sending traces to SigNoz.

💡 Tip

Need to enable or disable instrumentation for specific libraries? Check out our guide on selective instrumentation.

The OpenTelemetry Operator auto-injects instrumentation into your Nuxt.js pods without modifying your application image.

Step 1. Set up the OpenTelemetry Operator

Install the Operator and Collector following the K8s OTel Operator installation guide.

Step 2. Create the Instrumentation resource

Create instrumentation.yaml to configure Node.js auto-instrumentation:

instrumentation.yaml

apiVersion: opentelemetry.io/v1alpha1
kind: Instrumentation
metadata:
  name: nodejs-instrumentation
spec:
  exporter:
    endpoint: http://otel-collector-collector:4318
  propagators:
    - tracecontext
    - baggage
  nodejs:
    image: ghcr.io/open-telemetry/opentelemetry-operator/autoinstrumentation-nodejs:latest

Deploy this resource to your cluster.

Step 3. Add annotations to your deployment

Add these annotations to your pod template's metadata.annotations:

instrumentation.opentelemetry.io/inject-nodejs: "true"

Step 1. Set environment variables (PowerShell)

$env:OTEL_TRACES_EXPORTER="otlp"
$env:OTEL_EXPORTER_OTLP_ENDPOINT="https://ingest.<region>.signoz.cloud:443"
$env:OTEL_NODE_RESOURCE_DETECTORS="env,host,os"
$env:OTEL_SERVICE_NAME="<service_name>"
$env:OTEL_EXPORTER_OTLP_HEADERS="signoz-ingestion-key=<your-ingestion-key>"
$env:NODE_OPTIONS="--require @opentelemetry/auto-instrumentations-node/register"

Replace the following:

<region>: Your SigNoz Cloud region (us, eu, or in).
<your-ingestion-key>: Your SigNoz ingestion key.
<service_name>: Name of your service.

Step 2. Install OpenTelemetry packages

npm install --save @opentelemetry/api @opentelemetry/auto-instrumentations-node

Step 3. Run the application

npm run dev

💡 Tip

Need to enable or disable instrumentation for specific libraries? Check out our guide on selective instrumentation.

Step 1. Add OpenTelemetry to your Dockerfile

Dockerfile

FROM node:18-alpine

WORKDIR /app
COPY package*.json ./
RUN npm install

# Install OpenTelemetry
RUN npm install @opentelemetry/api @opentelemetry/auto-instrumentations-node

COPY . .
RUN npm run build

# Set OpenTelemetry environment variables
ENV OTEL_TRACES_EXPORTER="otlp"
ENV OTEL_EXPORTER_OTLP_ENDPOINT="https://ingest.<region>.signoz.cloud:443"
ENV OTEL_NODE_RESOURCE_DETECTORS="env,host,os"
ENV OTEL_SERVICE_NAME="<service_name>"
ENV OTEL_EXPORTER_OTLP_HEADERS="signoz-ingestion-key=<your-ingestion-key>"
ENV NODE_OPTIONS="--require @opentelemetry/auto-instrumentations-node/register"

CMD ["node", ".output/server/index.mjs"]

Step 2. Build and run

docker build -t nuxt-app . && docker run -p 3000:3000 nuxt-app

💡 Tip

Need to enable or disable instrumentation for specific libraries? Check out our guide on selective instrumentation.

Validate

After running your instrumented application, verify traces appear in SigNoz:

Generate traffic by visiting pages in your Nuxt.js application.
Open SigNoz and navigate to Services.
Click Refresh and look for your service name.
Go to Traces to view individual trace details.

Troubleshooting

Enable debug logging

export OTEL_LOG_LEVEL=debug

This outputs detailed information about span exports and configuration.

Traces not appearing?

Check environment variables: Ensure OTEL_EXPORTER_OTLP_ENDPOINT and OTEL_SERVICE_NAME are set correctly.
Verify network connectivity: Test the endpoint with curl https://ingest.<region>.signoz.cloud:443/v1/traces.
Check ingestion key: Ensure the key is valid and has the correct permissions.

Service not listed?

Wait a few minutes for data to propagate.
Ensure your application is receiving requests (traces are only generated on activity).
Verify the OTEL_SERVICE_NAME value matches what you expect in SigNoz.

Short-lived processes

If your application exits quickly, explicitly flush traces:

const { trace } = require('@opentelemetry/api');
// Before exit
await trace.getTracerProvider().forceFlush();

Code-Based Setup (Optional)

Step 1. Install OpenTelemetry packages

npm install --save @opentelemetry/api@^1.9.0 \
  @opentelemetry/sdk-node@^0.208.0 \
  @opentelemetry/auto-instrumentations-node@^0.67.0 \
  @opentelemetry/exporter-trace-otlp-http@^0.208.0

Step 2. Create the tracing file

Create server/tracing.js (or server/tracing.ts for TypeScript):

server/tracing.js

'use strict'
const process = require('process');
const opentelemetry = require('@opentelemetry/sdk-node');
const { getNodeAutoInstrumentations } = require('@opentelemetry/auto-instrumentations-node');
const { OTLPTraceExporter } = require('@opentelemetry/exporter-trace-otlp-http');
const { resourceFromAttributes } = require('@opentelemetry/resources');
const { ATTR_SERVICE_NAME } = require('@opentelemetry/semantic-conventions');

const exporterOptions = {
  url: 'https://ingest.<region>.signoz.cloud:443/v1/traces',
  headers: { 'signoz-ingestion-key': '<your-ingestion-key>' }
}

const traceExporter = new OTLPTraceExporter(exporterOptions);
const sdk = new opentelemetry.NodeSDK({
  traceExporter,
  instrumentations: [getNodeAutoInstrumentations()],
  resource: resourceFromAttributes({
    [ATTR_SERVICE_NAME]: '<service_name>'
  })
});

sdk.start();

process.on('SIGTERM', () => {
  sdk.shutdown()
    .then(() => console.log('Tracing terminated'))
    .catch((error) => console.log('Error terminating tracing', error))
    .finally(() => process.exit(0));
});

server/tracing.ts

import process from 'process';
import * as opentelemetry from '@opentelemetry/sdk-node';
import { getNodeAutoInstrumentations } from '@opentelemetry/auto-instrumentations-node';
import { OTLPTraceExporter } from '@opentelemetry/exporter-trace-otlp-http';
import { resourceFromAttributes } from '@opentelemetry/resources';
import { ATTR_SERVICE_NAME } from '@opentelemetry/semantic-conventions';

const exporterOptions = {
  url: 'https://ingest.<region>.signoz.cloud:443/v1/traces',
  headers: { 'signoz-ingestion-key': '<your-ingestion-key>' }
}

const traceExporter = new OTLPTraceExporter(exporterOptions);
const sdk = new opentelemetry.NodeSDK({
  traceExporter,
  instrumentations: [getNodeAutoInstrumentations()],
  resource: resourceFromAttributes({
    [ATTR_SERVICE_NAME]: '<service_name>'
  })
});

sdk.start();

process.on('SIGTERM', () => {
  sdk.shutdown()
    .then(() => console.log('Tracing terminated'))
    .catch((error) => console.log('Error terminating tracing', error))
    .finally(() => process.exit(0));
});

Replace the following:

<region>: Your SigNoz Cloud region (us, eu, or in). See endpoints.
<your-ingestion-key>: Your SigNoz ingestion key.
<service_name>: Name of your service.

Step 3. Import tracing in nuxt.config

Add this import at the top of your nuxt.config.js or nuxt.config.ts:

nuxt.config.js

import "./server/tracing";

export default defineNuxtConfig({
  // your config
})

Step 4. Run the application

npm run dev

💡 Tip

Need to enable or disable instrumentation for specific libraries? Check out our guide on selective instrumentation.

Setup OpenTelemetry Collector (Optional)

What is the OpenTelemetry Collector?

The OTel Collector acts as a middleman between your app and SigNoz. Instead of sending data directly, your application sends everything to the Collector first, which then forwards it along.

Why use it?

Cleaning up data — Filter out noisy traces you don't care about, or remove sensitive info before it leaves your servers.
Keeping your app lightweight — Let the Collector handle batching, retries, and compression instead of your application code.
Adding context automatically — The Collector can tag your data with useful info like which Kubernetes pod or cloud region it came from.
Future flexibility — Want to send data to multiple backends later? The Collector makes that easy without changing your app.

See Switch from direct export to Collector for step-by-step instructions.

Next steps

Instrument the client-side of your Nuxt app for full-stack tracing
Capture frontend metrics and vitals
Correlate traces with logs
Set up alerts for your application

Sample application

Check out the Sample Nuxt.js App for a complete working example.

Nuxt.js OpenTelemetry Instrumentation

Prerequisites

Send traces to SigNoz

Step 1. Set environment variables

Step 2. Install OpenTelemetry packages

Step 3. Run the application

Step 1. Set environment variables

Step 2. Install OpenTelemetry packages

Step 3. Deploy and run

Step 1. Set up the OpenTelemetry Operator

Step 2. Create the Instrumentation resource

Step 3. Add annotations to your deployment

Step 1. Set environment variables (PowerShell)

Step 2. Install OpenTelemetry packages

Step 3. Run the application

Step 1. Add OpenTelemetry to your Dockerfile

Step 2. Build and run

Validate

Troubleshooting

Enable debug logging

Traces not appearing?

Service not listed?

Short-lived processes

Code-Based Setup (Optional)

Step 1. Install OpenTelemetry packages

Step 2. Create the tracing file

Step 3. Import tracing in nuxt.config

Step 4. Run the application

Setup OpenTelemetry Collector (Optional)

What is the OpenTelemetry Collector?

Why use it?

Next steps

Sample application

Was this page helpful?