apm-agent-nodejs

elastic-apm-node is the official Node.js agent for Elastic APM, part of the Elastic Observability stack. Once required at the very top of an application (before any other dependency is imported), it monkey-patches over 40 popular modules — web frameworks (Express, Fastify, Koa, hapi), databases and caches (Postgres, MySQL, MongoDB, Redis, Elasticsearch, Cassandra), message brokers (Kafka), and cloud SDKs (AWS SDK v2/v3, Azure Functions) — to automatically capture distributed traces, transactions, spans, and unhandled errors with zero manual code changes.

Captured data is streamed over HTTP to an APM Server (self-hosted or on Elastic Cloud), which forwards it into Elasticsearch for visualization and alerting in Kibana. The agent also exposes a manual instrumentation API, an AWS Lambda and Azure Functions wrapper for serverless tracing, and an OpenTelemetry Bridge so teams already using the vendor-neutral OTel API can route spans and metrics through the same agent without rewriting instrumentation code.

Configuration is layered — start-time options, environment variables, and Kibana-managed central configuration — letting operators tune sampling rates, transaction limits, and stack-trace capture at runtime without redeploying. The project maintains active 3.x and 4.x branches and ships a large compatibility test matrix (via test-all-versions) covering the exact version ranges of every instrumented module.

What You Get

• Automatic instrumentation of 40+ modules — Express, Fastify, Koa, hapi, GraphQL, Postgres, MySQL, MongoDB, Redis, Elasticsearch, Kafka, and more — with no manual span creation required
• Built-in AWS Lambda and Azure Functions wrappers for tracing serverless invocations end-to-end
• An OpenTelemetry Bridge that lets manual OTel API instrumentation flow through the same agent and transport as the automatic instrumentation
• Automatic capture of unhandled exceptions and uncaught errors with full stack traces, correlated to the transaction in progress
• Runtime-adjustable configuration via Kibana central config, so sampling rate and capture limits can change without a redeploy
• A structured logger (pino with ECS formatting) so agent diagnostics correlate directly with Elasticsearch log data

Common Use Cases

• Express/Fastify/Koa API tracing - drop the agent into a Node.js API service to get request-level transactions and downstream DB/HTTP spans without instrumenting each route by hand
• Serverless observability - wrap AWS Lambda or Azure Functions handlers so cold starts, invocation duration, and errors show up in the same APM timeline as the rest of a service
• Cross-service distributed tracing - propagate trace context across HTTP calls between Node.js microservices to see a single trace spanning multiple deployments
• Error alerting - capture unhandled exceptions and framework-level errors automatically and route them into Kibana alerts instead of relying on scattered try/catch logging
• Gradual OpenTelemetry adoption - use the OTel Bridge to add vendor-neutral manual spans/metrics alongside the agent’s automatic instrumentation during a migration to OTel-native tooling

Under The Hood

Architecture The singleton exported by index.js (new Agent() in lib/agent.js) is the central orchestrator: it wires together an Instrumentation module (lib/instrumentation/) that hooks require-in-the-middle/import-in-the-middle to monkey-patch each supported module in lib/instrumentation/modules/ (45+ package-specific shims), a Metrics collector (lib/metrics/), a swappable APM transport behind lib/apm-client/apm-client.js (a real http-apm-client once started, a noop-apm-client before that), a layered config system (lib/config/config.js, schema.js, normalizers.js) that merges start-time options, environment variables, and Kibana central config, and object-filter-sequence-based filter pipelines for scrubbing errors, transactions, and spans before they’re sent. Serverless entry points (lib/lambda.js, Azure Functions instrumentation) and the lib/opentelemetry-bridge/ wrap the same core agent rather than duplicating capture logic.

Tech Stack Plain CommonJS with no build step, targeting Node >=14.17. Core runtime dependencies are mostly small Elastic-maintained utility packages (error-callsites, breadth-filter, object-filter-sequence, module-details-from-path) alongside require-in-the-middle/import-in-the-middle for module patching, agentkeepalive for HTTP connection pooling to the APM Server, pino with @elastic/ecs-pino-format for internal logging, and @opentelemetry/api/core/sdk-metrics for the OTel bridge and metrics export. Public TypeScript types are hand-authored in index.d.ts rather than compiled from a TS source tree. The dev dependency list is unusually large because it pulls in real versions of every instrumented client (MongoDB, Postgres, ioredis, KafkaJS, AWS SDK v2/v3, Knex, GraphQL, Express/Fastify/Koa/hapi) purely to exercise the compatibility matrix.

Code Quality Tests use tape, not a framework like Jest or Mocha, spread across 177 dedicated *.test.js files (313 JS files total under test/), backed by custom mock harnesses (_mock_apm_server.js, _mock_http_client.js, _mock_logger.js) and a schema validator (_validate_schema.js). A test-all-versions (tav) configuration reruns the same suites against multiple historical releases of each instrumented dependency to catch breakage across version ranges — a pattern rarely seen outside APM/tracing agents. ESLint (flat config) plus Prettier enforce style, with additional custom lint scripts checking license headers and YAML files. GitHub Actions run the standard suite, the tav compatibility matrix, an edge/nightly build, and a FIPS-mode test job.

What Makes It Unique The breadth of the per-module instrumentation matrix — 45+ individually shimmed packages spanning web frameworks, database drivers, message queues, and cloud SDKs — combined with first-class serverless wrappers (Lambda, Azure Functions) and a bidirectional OpenTelemetry Bridge that lets the same agent carry both proprietary and OTel-API-driven spans is unusual among Node.js instrumentation libraries. The instrumentation-agent pattern itself is standard practice among APM vendors, so the innovation is in execution depth and compatibility coverage rather than a novel architectural idea.