Node.js setup

Picks up from the Node.js quickstart. Read that first.

Choosing which auto-instrumentations to load

getNodeAutoInstrumentations() loads every available instrumentation. That's fine to start with — it's fast and the ones that don't apply are no-ops — but you can trim the list to save a few milliseconds of startup:

import { HttpInstrumentation } from "@opentelemetry/instrumentation-http"
import { ExpressInstrumentation } from "@opentelemetry/instrumentation-express"
import { PgInstrumentation } from "@opentelemetry/instrumentation-pg"
 
new NodeSDK({
  instrumentations: [
    new HttpInstrumentation(),
    new ExpressInstrumentation(),
    new PgInstrumentation()
  ]
  // ...
})

Exporter batching

The quickstart uses the default BatchSpanProcessor, which batches every 5 s or 512 spans. For most workloads this is fine. Two tuning knobs worth knowing about:

new BatchSpanProcessor(exporter, {
  maxQueueSize: 2048, // default 2048 — increase for burst workloads
  maxExportBatchSize: 512, // default 512
  scheduledDelayMillis: 5000 // default 5000 — drop to 1000 for fresher live traces
})

Don't drop scheduledDelayMillis below 1 s in production — you'll spend more on network roundtrips than you save in freshness.

Async context

The Node auto-instrumentation uses AsyncLocalStorage for context propagation. If you use domain (deprecated) or manually switch contexts with executionAsyncResource, spans can get attached to the wrong trace. Symptoms: a trace tree with an unexpected root span, or missing parents.

Fix: stop doing that. Use AsyncLocalStorage for your own request-scoped state and the context propagation will just work.

Graceful shutdown

Node SDKs drop in-flight spans when the process exits, which means a fast SIGTERM can truncate traces. Shutdown hook:

process.on("SIGTERM", () => {
  sdk.shutdown().finally(() => process.exit(0))
})

The quickstart includes this; double-check it's still there if you refactor.

Logs and metrics

V1 ingests traces only. Logs and metrics are on the roadmap but aren't in the product yet — if you configure metrics or logs exporters against the /v1/otel endpoint, they'll 404. Document that explicitly in your bootstrap:

// Do NOT configure metricExporter or logRecordProcessor — traces only in V1.