OpenTelemetry using Nuxt.js

This page explains how to configure OpenTelemetry in a Nuxt.js app to send telemetry data to Axiom.

OpenTelemetry provides a unified approach to collecting telemetry data from your Nuxt.js and TypeScript apps. This page demonstrates how to configure OpenTelemetry in a Nuxt.js app to send telemetry data to Axiom using OpenTelemetry SDK.

Prerequisites

Create an Axiom account.
Create a dataset in Axiom where you send your data.
Create an API token in Axiom with permissions to ingest data to the dataset you have created.

Install Node.js version 18 or newer.
Use your own app written in Nuxt.js, or follow this guide to create a new one.

Create new Nuxt.js app

Run the following command to create a new Nuxt.js app. Accept the default options during the initialization.

shell

npx nuxi@latest init my-nuxt-app
cd my-nuxt-app

Install dependencies

Install the required OpenTelemetry packages:

shell

npm install @opentelemetry/api @opentelemetry/sdk-node @opentelemetry/auto-instrumentations-node @opentelemetry/exporter-trace-otlp-proto @opentelemetry/sdk-trace-base @opentelemetry/resources @opentelemetry/semantic-conventions

Configure environment variables

Create a .env file in the root of your project to store your Axiom credentials:

dotenv

AXIOM_TOKEN=API_TOKEN
AXIOM_DATASET=DATASET_NAME

Configure Nuxt.js app

Configure your Nuxt app in nuxt.config.ts to expose the environment variables to the runtime:

typescript

export default defineNuxtConfig({
  compatibilityDate: '2026-01-05',
  devtools: { enabled: true },

  runtimeConfig: {
    axiomToken: process.env.AXIOM_TOKEN,
    axiomDataset: process.env.AXIOM_DATASET,
  },

  nitro: {
    experimental: {
      openAPI: true
    }
  }
});

Server setup

Create server directories

Create the necessary directories for your server-side code:

shell

mkdir -p server/api

mkdir -p server/plugins

Instrumentation plugin

Create the OpenTelemetry instrumentation plugin in server/plugins/instrumentation.ts. This file sets up the OpenTelemetry SDK and configures it to send traces to Axiom.

typescript

import { NodeSDK } from '@opentelemetry/sdk-node';
import { getNodeAutoInstrumentations } from '@opentelemetry/auto-instrumentations-node';
import { OTLPTraceExporter } from '@opentelemetry/exporter-trace-otlp-proto';
import { BatchSpanProcessor } from '@opentelemetry/sdk-trace-base';
import { resourceFromAttributes } from '@opentelemetry/resources';
import { ATTR_SERVICE_NAME } from '@opentelemetry/semantic-conventions';

export default defineNitroPlugin((nitroApp) => {
  console.log('Initializing OpenTelemetry in Nitro server...');
  console.log('- AXIOM_TOKEN:', process.env.AXIOM_TOKEN ? `${process.env.AXIOM_TOKEN.substring(0, 10)}...` : 'NOT SET');
  console.log('- AXIOM_DATASET:', process.env.AXIOM_DATASET || 'NOT SET');

  const traceExporter = new OTLPTraceExporter({
    url: 'https://api.axiom.co/v1/traces',
    headers: {
      'Authorization': `Bearer ${process.env.AXIOM_TOKEN}`,
      'X-Axiom-Dataset': process.env.AXIOM_DATASET || ''
    },
  });

  // Add export success/error logging for debugging
  const originalExport = traceExporter.export.bind(traceExporter);
  traceExporter.export = (spans, resultCallback) => {
    console.log(`Exporting ${spans.length} span(s) to Axiom...`);
    originalExport(spans, (result) => {
      if (result.code === 0) {
        console.log(' Spans exported successfully to Axiom');
      } else {
        console.error(' Export failed:', result.error);
      }
      resultCallback(result);
    });
  };

  const resource = resourceFromAttributes({
    [ATTR_SERVICE_NAME]: 'my-nuxt-app',
  });

  const sdk = new NodeSDK({
    spanProcessor: new BatchSpanProcessor(traceExporter),
    resource: resource,
    instrumentations: [getNodeAutoInstrumentations()],
  });

  sdk.start();

  console.log('OpenTelemetry started in Nitro server');
});

Example API endpoint

Create an example API endpoint in server/api/hello.ts to test your OpenTelemetry setup.

The example endpoint below demonstrates manual span creation. Each request to /api/hello creates a trace span and sends it to Axiom.

typescript

import { trace } from '@opentelemetry/api';

export default defineEventHandler((event) => {
  console.log('API endpoint hit: /api/hello');

  // Get the tracer from the global tracer provider
  const tracer = trace.getTracer('my-nuxt-app');

  // Create a manual span for this API request
  const span = tracer.startSpan('api.hello');
  span.setAttribute('http.method', 'GET');
  span.setAttribute('http.path', '/api/hello');

  const response = {
    message: 'Hello from Nuxt API!',
    timestamp: new Date().toISOString(),
    path: event.path
  };

  span.end();

  console.log('Manual span created and ended');

  return response;
});

Run instrumented app

In development mode

To run your Nuxt app with OpenTelemetry instrumentation in development mode:

shell

npm run dev

You see the following output in the console:

text

Nuxt 4.2.2 (with Nitro 2.12.9, Vite 7.3.0 and Vue 3.5.26)

  ➜ Local:    http://localhost:3000/

Initializing OpenTelemetry in Nitro server...
- AXIOM_TOKEN: xaat-xxxxx...
- AXIOM_DATASET: nuxt-traces
OpenTelemetry started in Nitro server

Test setup

Test your API endpoint to generate traces:

shell

curl http://localhost:3000/api/hello

You get the following response from the API endpoint:

JSON

{
  "message": "Hello from Nuxt API!",
  "timestamp": "2026-01-05T22:30:00.000Z",
  "path": "/api/hello"
}

After making 5-10 requests, you see the following output in the console:

text

Exporting 5 span(s) to Axiom...
Spans exported successfully to Axiom

In production mode

To build and run in production:

shell

# Build the application
npm run build

# Start the production server
npm run preview

After generating some traces by visiting your API endpoints, go to the Stream tab in Axiom, and then click your dataset. You see the traces appearing in the stream.

Project directory structure

Your Nuxt.js project has the following structure:

text

my-nuxt-app/
├── server/
│   ├── api/
│   │   └── hello.ts          # Example API endpoint
│   └── plugins/
│       └── instrumentation.ts # OpenTelemetry configuration
├── .env                       # Environment variables
├── nuxt.config.ts            # Nuxt configuration
├── package.json              # Dependencies and scripts
└── tsconfig.json             # TypeScript configuration (auto-generated)

Root-level files

.env: Stores environment variables (API token, dataset name)
nuxt.config.ts: Nuxt configuration file that exposes environment variables to the runtime
package.json: Lists dependencies and npm scripts
tsconfig.json: TypeScript configuration (auto-generated by Nuxt)

Server directory

The server/ directory contains all server-side code that runs in Nitro, Nuxt's server engine.

server/api/ directory contains API route handlers. Each file becomes an API endpoint:
- server/api/hello.ts → /api/hello
- server/api/users.ts → /api/users
- server/api/posts/[id].ts → /api/posts/:id
server/plugins/ directory contains Nitro plugins that run when the server starts:
- server/plugins/instrumentation.ts: Initializes OpenTelemetry SDK

Manual instrumentation

Manual instrumentation in Nuxt.js allows you to create custom spans for specific operations.

Initialize tracer

Import the OpenTelemetry API in any server file, such as server/api/hello.ts:

typescript

import { trace } from '@opentelemetry/api';

const tracer = trace.getTracer('my-nuxt-app');

Create spans

Wrap operations you want to trace:

typescript

export default defineEventHandler(async (event) => {
  const span = tracer.startSpan('database.query');

  try {
    // Your code here
    const data = await fetchDataFromDatabase();

    span.setStatus({ code: 0 }); // Success
    span.end();

    return data;
  } catch (error) {
    span.recordException(error);
    span.setStatus({ code: 2, message: error.message }); // Error
    span.end();

    throw error;
  }
});

Annotate spans

Add metadata to your spans, such as order.id, user.id, and order.amount:

typescript

const span = tracer.startSpan('process.order');

span.setAttribute('order.id', orderId);
span.setAttribute('user.id', userId);
span.setAttribute('order.amount', amount);

span.addEvent('payment_processed', {
  paymentMethod: 'credit_card',
  processorResponse: 'approved'
});

span.end();

Create nested spans

Create parent-child relationships between spans:

typescript

import { trace, context } from '@opentelemetry/api';

export default defineEventHandler(async (event) => {
  const tracer = trace.getTracer('my-nuxt-app');

  const parentSpan = tracer.startSpan('process.checkout');

  // Make parentSpan the active span
  await context.with(trace.setSpan(context.active(), parentSpan), async () => {
    // This span will be a child of parentSpan
    const childSpan = tracer.startSpan('validate.payment');
    await validatePayment();
    childSpan.end();

    // Another child span
    const childSpan2 = tracer.startSpan('create.order');
    await createOrder();
    childSpan2.end();
  });

  parentSpan.end();
});

Automatic instrumentation

Automatic instrumentation is already set up in the server/plugins/instrumentation.ts file:

typescript

instrumentations: [getNodeAutoInstrumentations()]

This automatically traces:

HTTP requests and responses
Database queries (MySQL, PostgreSQL, MongoDB, etc.)
Redis operations
File system operations
DNS lookups
And many more Node.js operations

Reference

List of OpenTelemetry Trace Fields

Field Category	Field Name	Description
Unique Identifiers
	_rowid	Unique identifier for each row in the trace data.
	span_id	Unique identifier for the span within the trace.
	trace_id	Unique identifier for the entire trace.
Timestamps
	_systime	System timestamp when the trace data was recorded.
	_time	Timestamp when the actual event being traced occurred.
HTTP Attributes
	attributes.http.method	HTTP method used for the request.
	attributes.http.path	The API path accessed during the request.
	attributes.http.status_code	HTTP response status code.
	attributes.http.route	Route pattern (for example, /api/:id).
	attributes.http.scheme	Protocol scheme (HTTP/HTTPS).
	attributes.http.user_agent	User agent string of the client.
Network Attributes
	attributes.net.host.port	Port number on the host receiving the request.
	attributes.net.peer.ip	IP address of the peer in the network interaction.
Operational Details
	duration	Time taken for the operation in nanoseconds.
	kind	Type of span (server, client, internal, producer, consumer).
	name	Name of the span (for example, 'api.hello').
	scope	Instrumentation scope.
	service.name	Name of the service generating the trace.
Resource Attributes
	resource.process.pid	Process ID of the Nitro server.
	resource.process.runtime.name	Runtime name (for example, 'nodejs').
	resource.process.runtime.version	Node.js version.
Telemetry SDK Attributes
	telemetry.sdk.language	Language of the telemetry SDK (javascript).
	telemetry.sdk.name	Name of the telemetry SDK (opentelemetry).
	telemetry.sdk.version	Version of the telemetry SDK.

import { SimpleSpanProcessor } from '@opentelemetry/sdk-trace-base';

const sdk = new NodeSDK({
  spanProcessor: new SimpleSpanProcessor(traceExporter), // Exports immediately
  resource: resource,
  instrumentations: [getNodeAutoInstrumentations()],
});

Sampling

To reduce the volume of traces, use the TraceIdRatioBasedSampler to sample a percentage of traces:

typescript

import { TraceIdRatioBasedSampler } from '@opentelemetry/sdk-trace-base';

const sdk = new NodeSDK({
  spanProcessor: new BatchSpanProcessor(traceExporter),
  sampler: new TraceIdRatioBasedSampler(0.5), // Sample 50% of traces
  resource: resource,
  instrumentations: [getNodeAutoInstrumentations()],
});

Custom resource attributes

Add custom attributes to all traces, such as service.version and deployment.environment:

typescript

const resource = resourceFromAttributes({
  [ATTR_SERVICE_NAME]: 'my-nuxt-app',
  [ATTR_SERVICE_VERSION]: '1.0.0',
  'deployment.environment': process.env.NODE_ENV || 'development',
  'service.namespace': 'production',
});

OpenTelemetry using Nuxt.js

Prerequisites

Create new Nuxt.js app

Install dependencies

Configure environment variables

Configure Nuxt.js app

Server setup

Create server directories

Instrumentation plugin

Example API endpoint

Run instrumented app

In development mode

Test setup

In production mode

Project directory structure

Root-level files

Server directory

Manual instrumentation

Initialize tracer

Create spans

Annotate spans

Create nested spans

Automatic instrumentation

Reference

List of OpenTelemetry Trace Fields

List of Imported Libraries

`@opentelemetry/sdk-node`

`@opentelemetry/auto-instrumentations-node`

`@opentelemetry/exporter-trace-otlp-proto`

`@opentelemetry/sdk-trace-base`

`@opentelemetry/resources`

`@opentelemetry/semantic-conventions`

`@opentelemetry/api`

Advanced configurations

Custom span processor

Sampling

Custom resource attributes