dd-trace for Node: npm install dd-trace, require and init it before any app code

TL;DR: Node APM with dd-trace: npm install dd-trace, then require and init the tracer before any other import. Initialization order is the classic failure. dd-trace for Node: install it, then require it FIRST The Node tracer has one hard rule: it must be loaded before the modules it instruments. The tracer patches modules as they load, which is why it must be first.

dd-trace for Node: install it, then require it FIRST

The Node tracer has one hard rule: it must be loaded before the modules it instruments. Get the order wrong and you get a running app with zero traces and no error.

Setup

npm install dd-trace

At the very top of your entry file, before everything else:

const tracer = require('dd-trace').init({
  service: 'my-service',
  env: 'prod',
  version: '1.2.3'
})

That is the whole integration for auto-instrumented frameworks (Express, Fastify, Nest, pg, redis, and the rest). The tracer patches modules as they load, which is why it must be first.

The traps, in order of frequency

1. Init after imports. If your entry file imports express before requiring dd-trace, express never gets patched. Move the tracer require to line one. In ESM, use --import dd-trace/register or the loader hook so it runs before your code.
2. No service/env/version. Pass them to init or set DD_SERVICE, DD_ENV, DD_VERSION. Defaults guess and your service catalog turns to mush.
3. Agent unreachable. Default is the agent on the same host. In containers set DD_AGENT_HOST to the agent, or DD_TRACE_AGENT_URL to the full URL. Connection refused here is silent, traces just never arrive.
4. Wrong site. DD_SITE for non-US1 orgs, same as everything else Datadog.
5. Major version jumps. dd-trace has breaking changes across majors (the docs ship a migration guide for 0.x through 5.x). Pin the major in package.json.

Verify

Start the app, hit an endpoint, check APM, Services. Also watch the tracer debug log on startup: it logs the agent endpoint it is using. If it says the wrong host, your env var did not take.

Serverless note: on Lambda, dd-trace works with the Datadog extension layer, but the init-first rule still applies inside the handler module.

When to use this

• This covers exactly what the title says: dd-trace for Node.
• You are setting this up for the first time, or auditing an existing setup.
• You want the key gotchas in one place before you start.

When not to use this

• You are doing a different workflow with dd-trace; these steps are specific to the title above.
• You need the full reference docs; this is the short path, not the manual.

The Node.js tracing docs: install with npm install dd-trace (Node 18+; dd-trace@latest-node16 for EOL Node 16), and the SDK must be initialized before app code loads. The docs call out the major-version migration guide for upgrades across 0.x-5.x. Verified against live docs 2026-09-26.