OpenTelemetry Auto-Instrumentations for Node.js

OpenTelemetry Auto-Instrumentations for Node.js is a metapackage that bundles the OpenTelemetry Node.js core and contrib instrumentations so you can capture traces, metrics, and logs from dozens of popular libraries and frameworks without touching your application code. Requiring the package’s register hook at startup wires up HTTP, Express, gRPC, database, messaging, and cloud instrumentations automatically, and everything is configurable through OpenTelemetry environment variables.

It also exposes a programmatic API for teams that want fine-grained control, letting you build a curated instrumentation list and pass per-instrumentation configuration into the OpenTelemetry SDK. The result is a fast path from an uninstrumented Node service to full distributed tracing across your stack.

What You Get

• A single metapackage that pulls in every officially supported OpenTelemetry Node.js instrumentation
• A --require @opentelemetry/auto-instrumentations-node/register hook that instruments an app with no code changes
• Environment-variable control over which instrumentations, exporters, and resource detectors are active
• A programmatic getNodeAutoInstrumentations() API for per-instrumentation configuration
• Bundled cloud and host resource detectors for AWS, GCP, Azure, Alibaba Cloud, and containers

Common Use Cases

• Adding distributed tracing to an existing Node service without editing application code
• Standardizing observability across many microservices with one shared dependency
• Exporting traces and metrics to an OTLP backend such as Jaeger, Tempo, or a vendor APM
• Selectively enabling or disabling instrumentations per environment via env vars

Under The Hood

Architecture

The package is a thin aggregation layer. src/utils.ts statically imports 40+ instrumentation classes (Http, Express, Grpc, MongoDB, Pg, Redis, KafkaJs, and more) plus cloud/host resource detectors, then getNodeAutoInstrumentations() instantiates the enabled subset based on the OTEL_NODE_ENABLED_INSTRUMENTATIONS / OTEL_NODE_DISABLED_INSTRUMENTATIONS env vars and any per-instrumentation config map. src/register.ts is the zero-code entry point: loaded via Node’s --require flag, it constructs an SDK with the resolved instrumentation list and resource detectors so telemetry starts flowing at process boot. src/index.ts re-exports the programmatic helpers for teams that wire the SDK themselves.

Tech Stack

Written in TypeScript (~98% of the repo) and published from the open-telemetry/opentelemetry-js-contrib Lerna/Nx monorepo. Its runtime dependencies are the 49 sibling @opentelemetry/instrumentation-* and @opentelemetry/resource-detector-* packages, layered on the OpenTelemetry JS API and SDK 2.0+. Tests run on Mocha with nyc for coverage; the build uses the shared tsconfig bases from the monorepo root.

Code Quality

The codebase is small, focused, and well-typed, with an exported InstrumentationConfigMap type giving consumers type-safe per-instrumentation configuration. Tests exist and are meaningful — test/utils.test.ts covers env-var parsing and instrumentation selection across ~18 cases and test/register.test.ts exercises the register hook against a test app. As part of the CNCF OpenTelemetry project it follows consistent Apache-2.0 headers, strict linting, and an actively enforced contribution process.

API Design The developer experience is a standout: a single node --require '@opentelemetry/auto-instrumentations-node/register' app.js yields full instrumentation with no code, while getNodeAutoInstrumentations(configMap) offers an ergonomic escape hatch for fine control. Configuration leans on documented, standard OTEL environment variables rather than bespoke options, and the README is thorough about exporters, resource detectors, and enable/disable semantics, keeping the boilerplate to get started near zero.