Quickstart

Prerequisites

Node.js >= 18 (for dd-trace v5)
A running Datadog Agent (or use agentless mode)

Setup

Install dd-trace

Add dd-trace to your project:

npm install dd-trace

Initialize the tracer

Initialize dd-trace before importing any other modules. This is critical — the tracer must load first to instrument your libraries.

CommonJS
ESM
Environment variable

Create a dedicated initialization file:

tracer.js

'use strict'

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

module.exports = tracer

Then require it as the very first line of your entry point:

server.js

require('./tracer') // Must be first!

const express = require('express')
const app = express()

app.get('/', (req, res) => {
  res.send('Hello World')
})

app.listen(3000)

For ES modules, use the --import flag when starting your application:

node --import dd-trace/register.js server.mjs

Or configure it in your package.json:

package.json

{
  "scripts": {
    "start": "node --import dd-trace/register.js server.mjs"
  }
}

See the ESM installation guide for more details.

Use NODE_OPTIONS to initialize without modifying your code:

DD_SERVICE=my-service DD_ENV=production NODE_OPTIONS='-r dd-trace/init' node server.js

The tracer must be initialized before any other require() calls. If you import express, pg, or other libraries before calling require('dd-trace').init(), those libraries will not be instrumented.

Configure the Datadog Agent connection

By default, dd-trace connects to the Datadog Agent at localhost:8126. Set these environment variables if your Agent runs elsewhere:

DD_AGENT_HOST=my-agent-host
DD_TRACE_AGENT_PORT=8126

Or pass them to init():

require('dd-trace').init({
  hostname: 'my-agent-host',
  port: 8126
})

Verify traces are being sent

Enable debug logging to verify the tracer is working:

DD_TRACE_DEBUG=true node server.js

You should see output like:

Sending 1 trace(s) with 3 span(s) to the agent at http://localhost:8126/v0.4/traces

Once traces are flowing, they appear in Datadog under APM > Traces.

What happens automatically

Once initialized, dd-trace automatically instruments your supported libraries with no additional code:

HTTP servers: Express, Fastify, Koa, Hapi, Restify, Next.js
HTTP clients: http, https, fetch, undici, axios
Databases: PostgreSQL, MySQL, MongoDB, Redis, Elasticsearch
Message queues: Kafka, RabbitMQ, SQS, BullMQ
And 100+ more — see the full plugin list

Next steps

Configuration Options

Customize service name, environment, sampling rates, and more.

Manual Instrumentation

Add custom spans to your business logic with tracer.trace().

All Integrations

Browse all 100+ supported libraries and frameworks.

Environment Variables

Full reference of all DD_* environment variables.

Introduction

Installation

Configuration

Prerequisites

Setup

What happens automatically

Next steps

Configuration Options

Manual Instrumentation

All Integrations

Environment Variables

Build docs developers (and LLMs) love

Introduction

Installation

Configuration

​Prerequisites

​Setup

​What happens automatically

​Next steps

Configuration Options

Manual Instrumentation

All Integrations

Environment Variables

Build docs developers (and LLMs) love

Prerequisites

Setup

What happens automatically

Next steps