Skip to main content
dd-trace v5 drops support for Node.js 16 and introduces a corrected TypeScript signature for tracer.trace. This guide covers all breaking changes and the steps to upgrade.

​
Breaking changes

Node.js 16 is no longer supported. Node.js 16 reached end-of-life in September 2023. dd-trace v5 requires Node.js 18 or later.

​
Node.js version requirement

dd-trace v5 requires Node.js >= 18. If your application runs on Node.js 16, you must upgrade Node.js before upgrading dd-trace. Check your current Node.js version: 
node --version

​
trace<T> TypeScript signature change

The TypeScript declaration for tracer.trace<T> has been updated to enforce that the callback always receives the span object. Previously the span parameter was technically optional, which was incorrect because the span must always be handled. Before (v4): 
// This was incorrectly allowed — span was optional
tracer.trace('operation.name', () => {
  // span not received
})
After (v5): 
// span is now required in the callback signature
tracer.trace('operation.name', (span) => {
  // span must be accepted
})
If you have TypeScript code that calls tracer.trace with a zero-argument callback, you must update those call sites to accept the span: 
// Update zero-argument callbacks to accept the span
tracer.trace('operation.name', (span) => {
  span.setTag('key', 'value')
})

​
Upgrade steps

1

Upgrade Node.js to 18 or later

dd-trace v5 requires Node.js 18 or later. Update your runtime before upgrading the package.Verify your version after upgrading:
node --version
# v18.x.x or later
Also update any .nvmrc, .node-version, Dockerfile, or CI configuration files that pin your Node.js version.
2

Install dd-trace v5

Install the latest version of dd-trace:
npm install dd-trace@latest
Or with yarn:
yarn add dd-trace@latest
Confirm the installed version:
npm show dd-trace version
3

Update tracer.trace TypeScript call sites

If you use TypeScript, search your codebase for calls to tracer.trace where the callback does not accept a span argument and update them:
// Before
tracer.trace('my.operation', () => {
  doWork()
})

// After
tracer.trace('my.operation', (span) => {
  doWork()
})
4

Run your test suite

Run your full test suite to catch any issues introduced by the upgrade:
npm test

​
Version compatibility table

dd-trace versionNode.js requirementStatus
v5 (current)>= 18Current
v4>= 16EOL
v3>= 14EOL
For any issues related to migrating, open an issue on the dd-trace-js GitHub repository or contact Datadog support.

Build docs developers (and LLMs) love

Get started for freeTalk to us