Required dependencies

npm install user@example.com
npm install dc-polyfill
npm install import-in-the-middle

No native build steps, pod installs, or Android linking are required. dd-trace is pure JavaScript. A running Datadog Agent (default: localhost:8126) is required at runtime to receive traces; it is not an npm dependency.

Project setup

1. Drop the source: if vendoring from source, place the source/ directory at your project root and add a path alias. For standard npm usage, npm install dd-trace is sufficient.

2. Initialize before all other requires: the tracer must be the first thing your process loads.

   // server.js  (CJS)
   const tracer = require('dd-trace').init({ /* options */ })
   // ... rest of your requires
   

   For ESM projects, use the loader flag:

   node --import dd-trace/initialize.mjs server.mjs
   

3. Environment variables (set in your .env or deployment config):

   DD_AGENT_HOST=localhost          # Datadog Agent host
   DD_TRACE_AGENT_PORT=8126         # Datadog Agent port
   DD_SERVICE=my-service            # Service name shown in Datadog UI
   DD_ENV=production                # Environment tag (production, staging, etc.)
   DD_VERSION=1.0.0                 # Version tag for deployment tracking
   DD_TRACE_ENABLED=true            # Master on/off switch
   DD_LOGS_INJECTION=true           # Inject trace IDs into log output
   

4. TypeScript: the package ships index.d.ts. Add to tsconfig.json:

   {
     "compilerOptions": {
       "types": ["dd-trace"]
     }
   }
   

5. Verify: start your app, make a request, and confirm spans appear in the Datadog APM UI or in the Agent debug output at http://localhost:8126/info.

Public API

tracer (default export)

import tracer from 'dd-trace'
// or
const tracer = require('dd-trace')

The singleton tracer instance. All tracing operations originate here. Use this to initialize instrumentation, start manual spans, and access the active scope.

tracer.init(options?)

tracer.init(options?: {
  service?: string
  env?: string
  version?: string
  hostname?: string
  port?: number
  flushInterval?: number
  logInjection?: boolean
  runtimeMetrics?: boolean
  plugins?: boolean
  debug?: boolean
}): Tracer

Bootstraps the tracer with configuration. Must be called once at process startup before any other modules are loaded. Returns the tracer instance for chaining. flushInterval: 0 forces immediate span flushing, useful in tests.

ext module (constants)

import { formats, kinds, priority, tags, types, exporters } from 'dd-trace/ext'
// or
const { formats, kinds, priority, tags, types, exporters } = require('dd-trace/ext')

Provides string/numeric constants for span metadata. Use tags to set well-known tag keys (e.g., HTTP method, status code) and priority to control sampling decisions (e.g., priority.USER_KEEP). Use kinds to label spans as 'client', 'server', 'producer', 'consumer', or 'internal'.

Working examples

Scenario - Basic Express service with automatic instrumentation

dd-trace auto-instruments Express, HTTP, and many other libraries. No manual span creation is needed for standard request tracing.

// server.ts
import tracer from 'dd-trace'

tracer.init({
  service: 'my-api',
  env: process.env.NODE_ENV ?? 'development',
  version: '1.0.0',
  logInjection: true,
  flushInterval: 2000,
})

import express from 'express'

const app = express()

app.get('/', (_req, res) => {
  res.json({ status: 'ok' })
})

app.listen(3000, () => {
  console.log('Listening on :3000')
})

Scenario - Manual span creation for a background job

When auto-instrumentation does not cover a code path (e.g., a queue consumer or batch job), create spans manually using tracer.startSpan / tracer.scope().activate.

import tracer from 'dd-trace'
import { kinds, tags } from 'dd-trace/ext'

tracer.init({ service: 'job-worker', env: 'production' })

async function processJob(jobId: string): Promise<void> {
  const span = tracer.startSpan('job.process', {
    tags: {
      [tags.RESOURCE_NAME]: `job/${jobId}`,
      'span.kind': kinds.INTERNAL,
      'job.id': jobId,
    },
  })

  try {
    // simulate work
    await new Promise(resolve => setTimeout(resolve, 50))
    span.setTag('job.result', 'success')
  } catch (err) {
    span.setTag('error', err)
    throw err
  } finally {
    span.finish()
  }
}

processJob('abc-123').then(() => console.log('done'))

Scenario - Sampling priority control via ext/priority

Use priority constants to force-keep or force-drop specific traces, overriding the default sampling rate.

import tracer from 'dd-trace'
import { priority } from 'dd-trace/ext'

tracer.init({ service: 'checkout', env: 'production' })

function handleCheckout(orderId: string): void {
  const span = tracer.startSpan('checkout.process')

  // Force-keep all checkout spans for business-critical auditing
  span.setTag('sampling.priority', priority.USER_KEEP)
  span.setTag('order.id', orderId)

  try {
    // ... business logic
  } finally {
    span.finish()
  }
}

handleCheckout('order-9999')

File walkthrough

• index.js - Root CJS entry point; delegates entirely to packages/dd-trace. This is what require('dd-trace') resolves to.
• index.d.ts - TypeScript declarations for the full public API including Tracer, Span, SpanContext, and plugin configuration types.
• init.js - Convenience entry for node --require dd-trace/init; calls tracer.init() with zero configuration using environment variables only.
• initialize.mjs - ESM counterpart to init.js; used with --import dd-trace/initialize.mjs for ES module projects.
• loader-hook.mjs - Implements the Node.js ESM loader hook that enables import-in-the-middle to wrap ES modules for instrumentation.
• register.js - Registers the ESM loader hook programmatically; used internally and by advanced setups.
• version.js - Exports the semver string of the current build.
• ext/index.js - Aggregates and re-exports all constant namespaces (formats, kinds, priority, tags, types, exporters).
• packages/ - Monorepo-style subdirectories containing the core tracer, plugins for each instrumented library, and supporting utilities.
• integration-tests/ - Full integration test apps (Express, ESM, AppSec) used in CI; useful as reference implementations.
• esbuild.js / webpack.js - Bundler entry-point configurations. Needed if you bundle your Node.js app; tracer has specific bundling requirements.
• scripts/ - Maintenance scripts (version bumping, supported-version matrix generation, etc.).

Common pitfalls and fixes

• Tracer initialized too late: any require/import of an instrumented library before tracer.init() will not be patched. Fix: make tracer.init() the absolute first line of your entry file, before all other imports.
• ESM projects not instrumented: using import tracer from 'dd-trace' at the top of an ESM file is not sufficient because static imports are hoisted. Fix: use node --import dd-trace/initialize.mjs CLI flag or register.js before the app module loads.
• Agent not reachable: spans are silently dropped if the Datadog Agent is not running at DD_AGENT_HOST:DD_TRACE_AGENT_PORT. Fix: verify with curl http://localhost:8126/info and ensure the Agent container/process is healthy.
• Bundling breaks instrumentation: esbuild/webpack tree-shaking or module rewriting breaks the monkey-patching that dd-trace depends on. Fix: mark dd-trace as external in your bundler config and load it from node_modules at runtime.
• flushInterval too high in short-lived processes: spans from scripts or Lambda functions may not be flushed before process exit. Fix: set flushInterval: 0 or call tracer.close() and await its promise before exiting.
• Conflicting import-in-the-middle versions: if your project or a dependency pins a different version of import-in-the-middle, ESM instrumentation silently breaks. Fix: deduplicate with npm dedupe and ensure only one version resolves.

Vibe-coding prompt template

I have a Node.js project and I want to integrate the dd-trace APM tracer.
The source is in the `source/` directory and the integration guide is in `USAGE.md`.
The upstream npm package is `user@example.com`.

Please help me integrate it step by step:

1. Read `USAGE.md` fully before writing any code.
2. Install the required dependencies listed in the "Required dependencies" section.
3. Add tracer initialization as the very first statement in my entry file
   (`src/server.ts` or equivalent), using `tracer.init()` with the options
   appropriate for my project (service name, env, version).
4. Set the required environment variables in my `.env` file.
5. If my project uses ES modules (`.mjs` or `"type": "module"` in package.json),
   configure the `--import dd-trace/initialize.mjs` loader flag in my start script.
6. Add a manual span example around the most important business-logic function
   in my codebase, using `tracer.startSpan()` and the `ext` constants from
   `source/ext/index.js`.
7. Show me how to verify traces are being sent by checking the Datadog Agent.
8. Warn me about any pitfalls specific to my project setup (ESM, bundler, etc.)
   as listed in USAGE.md.

Only use symbols and APIs that are documented in USAGE.md. Do not invent methods.

License and credit

dd-trace is released under the BSD 3-Clause License (see source/LICENSE). Copyright Datadog, Inc. and contributors.

Upstream package: dd-trace on npm Upstream repository: github.com/DataDog/dd-trace-js

This product’s unique contribution is clean room implementation of valuable code block into AVCP compatible standard.

The full install guide and integration prompts unlock after purchase.