Configuration
Configure which parts of your Nuxt application are traced and how the OpenTelemetry SDK is initialized.
Configure module options
Set module options under the nuxtOtel key in your Nuxt configuration:
export default defineNuxtConfig({
nuxtOtel: {
// Enable built-in OpenTelemetry SDK (Node.js only)
instrument: true,
// Enable DevTools UI at /__nuxt-otel
devtools: true,
},
})
Options reference
| Option | Type | Default | Description |
|---|---|---|---|
instrument | boolean | false | Enable the built-in NodeSDK for OTLP export |
devtools | boolean | false | Enable the DevTools UI |
Configure tracing channels
Enable or disable specific diagnostic channels via the top-level tracingChannel Nuxt option:
export default defineNuxtConfig({
tracingChannel: {
nuxt: true, // Nuxt render lifecycle
h3: true, // H3 request handling
srvx: true, // Server route requests
unstorage: true, // Storage operations
},
})
Set tracingChannel: true to enable all channels, or false to disable all.
Configure OTel SDK exporters
When instrument: true, the built-in NodeSDK exports traces via OTLP. Configure it using standard OpenTelemetry environment variables:
| Variable | Description | Values |
|---|---|---|
OTEL_TRACES_EXPORTER | Trace exporter | otlp, console, none |
OTEL_METRICS_EXPORTER | Metrics exporter | otlp, console, prometheus, none |
OTEL_LOGS_EXPORTER | Logs exporter | otlp, console, none |
Use a custom instrumentation setup
When you need full control over the OpenTelemetry SDK, disable the built-in setup and provide your own:
export default defineNuxtConfig({
nuxtOtel: {
instrument: false,
},
})
Then create a Nitro plugin:
import { defineNitroPlugin } from 'nitropack/runtime'
import { NodeSDK } from '@opentelemetry/sdk-node'
import { OTLPTraceExporter } from '@opentelemetry/exporter-trace-otlp-http'
import { Resource } from '@opentelemetry/resources'
import { SEMRESATTRS_SERVICE_NAME } from '@opentelemetry/semantic-conventions'
export default defineNitroPlugin(() => {
const sdk = new NodeSDK({
resource: new Resource({
[SEMRESATTRS_SERVICE_NAME]: 'my-nuxt-app',
}),
traceExporter: new OTLPTraceExporter({
url: 'http://my-collector:4318/v1/traces',
}),
})
sdk.start()
})
You can use any exporter (Console, Jaeger, Zipkin) or add auto-instrumentations like @opentelemetry/instrumentation-http.
Forward data to the DevTools UI
When using a custom instrumentation setup, you can still forward spans and logs to the DevTools UI by exporting them to the OTLP HTTP endpoint:
{devServerUrl}/__nuxt-otel-ingest
The endpoint accepts both trace and log OTLP JSON payloads (/v1/traces and /v1/logs). This lets you use any OTel SDK or collector to push data into the DevTools UI without relying on the built-in NodeSDK.