Skip to main content
dd-trace provides out-of-the-box instrumentation for many popular frameworks and libraries through a plugin system. By default, all built-in plugins are enabled and activate automatically when you require a supported library after calling tracer.init().
tracer.init() must be called before importing any other modules. Place it at the very top of your application entry point.

​
How the plugin system works

When your application requires a supported library, dd-trace intercepts the require call and wraps the relevant functions with tracing logic. No code changes to your application are needed beyond the initial tracer.init() call. 
// Must be first
const tracer = require('dd-trace').init()

// All subsequent requires are automatically instrumented
const express = require('express')
const pg = require('pg')
const redis = require('redis')
Each supported library maps to one or more plugin packages under packages/datadog-plugin-*/. The plugin is loaded lazily the first time the corresponding npm package is required.

​
Disabling specific plugins

All plugins are enabled by default. Pass false to tracer.use() to disable a specific plugin: 
const tracer = require('dd-trace').init()

// Disable the express plugin entirely
tracer.use('express', false)
To disable all built-in plugins and opt in selectively, set plugins: false in init(): 
const tracer = require('dd-trace').init({ plugins: false })

// Re-enable only what you need
tracer.use('express')
tracer.use('pg', { service: 'pg-cluster' })

​
Configuring plugins with tracer.use()

Use tracer.use(pluginName, config) to enable and configure a plugin at runtime. Configuration applied here overrides the defaults. 
const tracer = require('dd-trace').init()

// Configure the PostgreSQL plugin with a custom service name
tracer.use('pg', {
  service: 'pg-cluster'
})
The tracer.use() method is chainable and returns the tracer instance: 
const tracer = require('dd-trace')
  .init()
  .use('pg', { service: 'pg-primary' })
  .use('redis', { allowlist: ['get', 'set'] })

​
Common plugin options

All plugins accept these base options:
OptionTypeDefaultDescription
enabledbooleantrueEnable or disable the plugin.
servicestring—Override the service name for spans created by this plugin.
measuredboolean—Whether to measure the span for metrics.
Web framework plugins additionally support:
OptionTypeDescription
blockliststring | RegExp | Function | ArrayPaths that should not be instrumented.
allowliststring | RegExp | Function | ArrayPaths that should be instrumented (all others are skipped).
headersstring[]Request/response headers to capture as span tags.
validateStatus(code: number) => booleanCallback to determine if a status code is an error.
hooks.request(span, req, res) => voidHook called just before the request span finishes.
middlewarebooleanWhether to create spans for individual middleware functions.

​
Span hooks

Web framework plugins support span hooks that let you add custom tags to spans created by the plugin: 
const tracer = require('dd-trace').init()

tracer.use('express', {
  hooks: {
    request: (span, req, res) => {
      span.setTag('customer.id', req.query.id)
    }
  }
})
The hook receives the active span plus any contextual objects (request, response) relevant to the integration. Hooks are currently supported for web framework plugins.

​
Supported plugin categories

Web Frameworks

Express, Fastify, Koa, Hapi, Next.js, Hono, Restify, Connect, Moleculer

Databases

PostgreSQL, MySQL, MongoDB, Redis, Elasticsearch, Cassandra, and more

Messaging

Kafka, RabbitMQ, BullMQ, Google Cloud Pub/Sub, AWS SQS/SNS, Azure

AI/ML

OpenAI, Anthropic, LangChain, LangGraph, Vertex AI, Google GenAI

Testing

Jest, Mocha, Cucumber, Cypress, Playwright, Vitest, Selenium

All plugins

Complete categorized list of all 100+ supported plugins

Build docs developers (and LLMs) love

Get started for freeTalk to us