Node.js Selective Auto-Instrumentation Guide

Auto-instrumentation enables many libraries by default. Use environment variables or code to enable only what you need.

These steps work the same way regardless of deployment. Only your OTLP endpoint and ingestion key differ.

Prerequisites

Node.js 20.6.0+ with OpenTelemetry set up (see Node.js instrumentation guide)
If you're on Node 18, use 18.19.0+. Node 18 reached end of life on March 27, 2025.
OpenTelemetry SDK installed and configured

Configure selective instrumentation

No code changes required. Configure using environment variables.

Enable or disable specific libraries

# Enable only HTTP and Express
export OTEL_NODE_ENABLED_INSTRUMENTATIONS="http,express"
 
# Disable file system and gRPC
export OTEL_NODE_DISABLED_INSTRUMENTATIONS="fs,grpc"

Use library names without the @opentelemetry/instrumentation- prefix. See the full list of supported libraries.

If both variables are set, OTEL_NODE_ENABLED_INSTRUMENTATIONS applies first, then OTEL_NODE_DISABLED_INSTRUMENTATIONS. A library in both lists will be disabled.

Run your application

export OTEL_TRACES_EXPORTER="otlp"
export OTEL_EXPORTER_OTLP_ENDPOINT="https://ingest.<region>.signoz.cloud:443"
export OTEL_EXPORTER_OTLP_HEADERS="signoz-ingestion-key=<your-ingestion-key>"
export OTEL_SERVICE_NAME="<service-name>"
export OTEL_RESOURCE_ATTRIBUTES="service.version=<service-version>"
export OTEL_NODE_RESOURCE_DETECTORS="env,host,os"
export OTEL_NODE_ENABLED_INSTRUMENTATIONS="http,express"
export NODE_OPTIONS="--require @opentelemetry/auto-instrumentations-node/register"
node app.js

Verify these values:

<service-name>: Your service name (e.g., payment-service)
<region>: Your SigNoz Cloud region.
<your-ingestion-key>: Your SigNoz ingestion key
<service-version> (optional): Your release version, image tag, or git SHA (e.g., 1.4.2, a01dbef8).

Set service.version to a per-build value, not a static string. SigNoz detects a deployment each time this value changes. Common sources:

Bash / shell: service.version=$(git rev-parse --short HEAD)
GitHub Actions: service.version=${{ github.sha }}
GitLab CI: service.version=$CI_COMMIT_SHORT_SHA
Kubernetes: inject from your Helm chart image tag or CI variable

Environment variables only work with no-code auto-instrumentation (NODE_OPTIONS="--require @opentelemetry/auto-instrumentations-node/register"). For code-based setup, use the Code-based tab.

Configure instrumentations directly in your setup file.

Update your instrumentation file

const { NodeSDK } = require('@opentelemetry/sdk-node')
const { OTLPTraceExporter } = require('@opentelemetry/exporter-trace-otlp-http')
const { getNodeAutoInstrumentations } = require('@opentelemetry/auto-instrumentations-node')
 
const instrumentations = getNodeAutoInstrumentations({
  '@opentelemetry/instrumentation-fs': { enabled: false },
  '@opentelemetry/instrumentation-http': { enabled: true },
  '@opentelemetry/instrumentation-express': { enabled: true },
  '@opentelemetry/instrumentation-dns': { enabled: false },
  '@opentelemetry/instrumentation-grpc': { enabled: false },
})
 
const sdk = new NodeSDK({
  traceExporter: new OTLPTraceExporter({
    url: 'https://ingest.<region>.signoz.cloud:443/v1/traces',
    headers: { 'signoz-ingestion-key': '<your-ingestion-key>' }
  }),
  instrumentations: [instrumentations],
})
 
sdk.start()

<region>: Your SigNoz Cloud region.
<your-ingestion-key>: Your SigNoz ingestion key

Run your application

node -r ./instrumentation.js app.js

Validate

Enable debug logging to verify which instrumentations are active:

export OTEL_LOG_LEVEL=debug

Check the output for lines showing which instrumentations loaded.

Troubleshooting

Still not seeing data in SigNoz? Work through Debug missing traces, logs, and metrics, which covers SDK diagnostics, Collector connectivity, and the common ingestion errors for all three signals.

No traces appearing in SigNoz

Verify OTEL_EXPORTER_OTLP_ENDPOINT and OTEL_EXPORTER_OTLP_HEADERS are set correctly.
Check network connectivity to the SigNoz endpoint.

Missing or incomplete spans

Confirm the instrumentation library is enabled via OTEL_NODE_ENABLED_INSTRUMENTATIONS.
For no-code setup, ensure NODE_OPTIONS="--require @opentelemetry/auto-instrumentations-node/register" is set.

Invalid ingestion key

Format should be: signoz-ingestion-key=<your-ingestion-key>
Check for extra spaces or quotes.

Next steps

Manual instrumentation to add custom spans
Node.js instrumentation guide for full setup
Exclude HTTP endpoints such as health checks, etc.

If you need help with the steps in this topic, please reach out to us on SigNoz Community Slack. If you are a SigNoz Cloud user, please use in product chat support located at the bottom right corner of your SigNoz instance or contact us at cloud-support@signoz.io.