Auto-instrumentation enables many libraries by default. Use environment variables or code to enable only what you need.
Prerequisites
- Node.js 18+ application instrumented with OpenTelemetry (see Node.js instrumentation guide)
- 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_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
Replace <region>, <your-ingestion-key>, and <service-name> with your values.
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()
Replace <region> and <your-ingestion-key> with your values.
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
No traces appearing in SigNoz
- Verify
OTEL_EXPORTER_OTLP_ENDPOINTandOTEL_EXPORTER_OTLP_HEADERSare 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
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.
