dd-trace

dd-trace is the official Node.js client library for Datadog Application Performance Monitoring. Installed via npm install dd-trace and initialized at the top of an entrypoint (or preloaded with -r dd-trace/init), it automatically patches over a hundred popular Node.js libraries and frameworks — Express, Fastify, Koa, Next.js, gRPC, database drivers, message queues, and more — to emit distributed traces, runtime metrics, and logs correlation data to a Datadog Agent without requiring manual span instrumentation in most cases.

Beyond core tracing, dd-trace bundles the rest of Datadog’s Node.js observability surface into one package: continuous profiling, Application Security Management (WAF-based blocking, RASP, and IAST vulnerability scanning), Dynamic Instrumentation for setting breakpoints and log probes in production without redeploying, CI Visibility with flaky-test detection and intelligent test selection, and LLM Observability for tracing calls to OpenAI, Anthropic, LangChain, and other AI SDKs. Each integration lives in its own workspace package (datadog-plugin-*), letting the tracer support a wide instrumentation matrix while keeping individual integrations isolated and independently maintained.

What You Get

• Automatic distributed tracing across 100+ supported libraries (Express, Koa, Fastify, Next.js, gRPC, HTTP, popular database and queue clients) with zero manual span code required for standard cases
• Continuous profiling (CPU, heap, and event-loop delay) correlated directly with traces so you can see which request paths drive resource usage
• Application Security Management: a bundled WAF for blocking known attack patterns, RASP for runtime exploit prevention, and IAST for in-app vulnerability scanning
• Dynamic Instrumentation for attaching log probes and inspecting variables in a running production process without a redeploy
• CI Visibility and Test Optimization — early flake detection, intelligent test runner (skip tests unaffected by a change), and per-test flakiness tracking across mocha, jest, vitest, playwright, and cypress
• LLM Observability spans for OpenAI, Anthropic, LangChain, LangGraph, Google GenAI, and other AI SDKs, plus OpenTelemetry and OpenFeature interoperability bridges

Common Use Cases

• Adding distributed tracing to a Node.js microservice fleet so requests can be followed end-to-end across services and downstream calls in Datadog’s APM UI
• Diagnosing production CPU or memory spikes by pairing continuous profiling data with the specific traced requests that triggered them
• Blocking and monitoring application-layer attacks (SQLi, SSRF, etc.) at runtime via AppSec’s WAF and RASP without changing application code
• Speeding up CI pipelines by using Test Optimization’s intelligent test runner and early flake detection to skip unaffected or known-flaky tests
• Tracking cost, latency, and output quality of LLM-backed features by instrumenting calls to OpenAI/Anthropic/LangChain through LLM Observability

Under The Hood

Architecture dd-trace boots through init.js, which first runs a defensive guardrails wrapper (packages/dd-trace/src/guardrails) around the real initializer so instrumentation failures can never crash the host application, then requires packages/dd-trace/src/index.js. That entrypoint checks DD_TRACE_ENABLED/OTEL_TRACES_EXPORTER and swaps in either a no-op proxy or the real proxy.js, which wires together the DatadogTracer, a PluginManager, runtime metrics, telemetry, and service-naming logic. The bulk of instrumentation lives in a monorepo workspace split: packages/datadog-instrumentations (143 files) contains lightweight hooks that subscribe to each target library’s internals via Node’s diagnostics_channel, while a parallel packages/datadog-plugin-* package (108 of them, one per integration — Express, Redis, Kafka, OpenAI, etc.) turns those channel events into spans. Cross-cutting subsystems — AppSec (WAF/RASP/IAST), the Dynamic Instrumentation debugger, the profiler, LLM Observability, and CI Visibility’s test optimization — are separate modules under packages/dd-trace/src that attach to the same core tracer, each independently enabled by config/env vars.

Tech Stack The library is almost entirely plain JavaScript (98.9%) targeting Node.js >=22 for its current v6 release line (v5 remains in maintenance for Node 18), with a thin TypeScript typings surface (index.d.ts) checked via tsc --noEmit rather than compiled. Runtime dependencies are deliberately minimal — dc-polyfill (diagnostics_channel polyfill), import-in-the-middle (ESM instrumentation hooking), and opentracing for legacy API compatibility — since this package ships inside every instrumented consumer’s process. The devDependency set is extensive by contrast: mocha with c8/nyc for coverage, sinon and proxyquire for test doubles, nock for HTTP mocking, a large custom ESLint config plus an in-repo eslint-rules/ package for project-specific lint rules, and husky-managed git hooks. CI runs across 20+ dedicated GitHub Actions workflows (appsec.yml, profiling.yml, debugger.yml, llmobs.yml, apm-integrations.yml, and more), with docker-compose used to spin up real service dependencies for integration tests.

Code Quality The test suite is large and framework-specific: 472 spec files live under packages/dd-trace/test alone, with a separate integration-tests/ tree exercising real per-framework instrumentation end-to-end. Tests run on mocha with sinon/proxyquire/nock for isolation and c8/nyc for coverage enforcement. The team enforces conventions beyond standard linting — a dedicated eslint-rules/ package, a verify-carrier-fields script, and CODEOWNERS auditing (codeowners-audit) all run in CI. Runtime code itself is plain JavaScript rather than statically typed, with TypeScript used only to validate the public .d.ts surface, so type safety is enforced at the API boundary rather than throughout the implementation. The guardrails-wrapped init path is a notable defensive pattern: instrumentation errors are caught so they can’t take down the application that loaded the tracer.

What Makes It Unique dd-trace goes well past being a plain distributed-tracing client — it’s a converged observability agent bundled as one npm package. Continuous profiling, a production-safe Dynamic Instrumentation debugger (attach log probes and inspect state without redeploying), Application Security Management (WAF blocking, RASP, and IAST scanning in the same process as the tracer), CI Test Optimization (flaky-test quarantine and intelligent test selection), and LLM Observability for AI SDK calls are all first-class subsystems rather than separate packages. Combined with a 108-plugin integration matrix spanning everything from Express to Vitest to Anthropic’s SDK, and interoperability bridges for OpenTelemetry and OpenFeature, this breadth is unusual for a single auto-instrumenting library.