OpenTelemetry Node SDK

Instrument Node.js 24 services with the OpenTelemetry Node SDK - auto-instrument HTTP and database drivers, export OTLP traces, and add manual spans for business logic.

Recipe

Quick-reference recipe card - copy-paste ready.

// src/instrumentation.ts
import { NodeSDK } from "@opentelemetry/sdk-node";
import { getNodeAutoInstrumentations } from "@opentelemetry/auto-instrumentations-node";
import { OTLPTraceExporter } from "@opentelemetry/exporter-trace-otlp-http";
import { Resource } from "@opentelemetry/resources";
import { ATTR_SERVICE_NAME } from "@opentelemetry/semantic-conventions";
 
const sdk = new NodeSDK({
  resource: new Resource({ [ATTR_SERVICE_NAME]: "orders-api" }),
  traceExporter: new OTLPTraceExporter(),
  instrumentations: [getNodeAutoInstrumentations()],
});
 
sdk.start();

// src/main.ts
import "./instrumentation.js";
import { startServer } from "./server.js";
startServer();

When to reach for this:

• Need distributed traces across microservices.
• Debugging p99 latency with waterfall views in Honeycomb/Datadog/Jaeger.
• Standardizing instrumentation before picking an APM vendor.
• Replacing ad-hoc console.time timing in production.

Working Example

// instrumentation.ts
import { NodeSDK } from "@opentelemetry/sdk-node";
import { getNodeAutoInstrumentations } from "@opentelemetry/auto-instrumentations-node";
import { OTLPTraceExporter } from "@opentelemetry/exporter-trace-otlp-http";
import { OTLPMetricExporter } from "@opentelemetry/exporter-metrics-otlp-http";
import { PeriodicExportingMetricReader } from "@opentelemetry/sdk-metrics";

// server.ts
import express from "express";
import { trace } from "@opentelemetry/api";
 
const app = express();
const tracer = trace.getTracer("orders");
 
app.get("/orders/:id", 

What this demonstrates:

• Resource attributes identify service in trace backend.
• Separate OTLP endpoints for traces and metrics (common in collectors).
• FS instrumentation disabled to reduce noise.
• Graceful sdk.shutdown() on SIGTERM flushes pending spans.

Deep Dive

How It Works

• SDK registers tracers and meters with the global @opentelemetry/api.
• Auto-instrumentation patches http, https, fetch, pg, ioredis, etc. at require time.
• Spans export via OTLP (OpenTelemetry Protocol) to collector or agent.
• W3C traceparent header propagates context to downstream HTTP calls.

Environment Variables

Load Order

// CORRECT
import "./instrumentation";
import express from "express";
 
// WRONG - missed HTTP spans
import express from "express";
import "./instrumentation";

• NestJS: import "./instrumentation" first line in main.ts.
• tsx dev: node --import ./src/instrumentation.ts src/main.ts.

Sampling

OTEL_TRACES_SAMPLER=parentbased_traceidratio
OTEL_TRACES_SAMPLER_ARG=0.1

• 10% head sampling for high-RPS services - adjust cost vs coverage.
• Always sample errors if vendor supports tail-based sampling.

Gotchas

• Instrumentation after imports - missing HTTP spans. Fix: instrumentation first line.
• Double instrumentation - vendor agent + OTel SDK conflict. Fix: pick one path per signal.
• High-cardinality span attributes - userId on every span explodes cost. Fix: low-cardinality attrs only.
• FS spans noise - thousands of readFile spans. Fix: disable @opentelemetry/instrumentation-fs.
• No shutdown on SIGTERM - lost spans on deploy. Fix: sdk.shutdown() in termination handler.
• Dev without collector - export errors flood logs. Fix: OTEL_TRACES_EXPORTER=none locally or run Jaeger docker.

Alternatives

FAQs

Related

• Observability Basics - three pillars intro
• Metrics that Matter - RED metrics
• APM Tools - Datadog, Honeycomb patterns
• Request Correlation IDs - traceparent header

Stack versions: This page was written for Node.js 24.18.0 (Active LTS), npm 10+, TypeScript 5.6+, Express 5, Fastify 5, and NestJS 11.