Skip to main content
dd-trace instruments database drivers to produce spans for every query or command. Each span includes the database type, host, port, and the sanitized query or command.

​
Supported databases

PostgreSQL

pg

MySQL

mysql / mysql2

MariaDB

mariadb

MongoDB

mongodb / mongoose

Redis

redis / ioredis

Valkey

iovalkey

Elasticsearch

elasticsearch / @elastic/elasticsearch

OpenSearch

@opensearch-project/opensearch

Cassandra

cassandra-driver

CouchBase

couchbase

Memcached

memcached

OracleDB

oracledb

SQL Server

tedious

Prisma

@prisma/client

Knex

knex

Aerospike

aerospike

​
Common configuration options

All database plugins extend the Instrumentation interface and accept:
OptionTypeDefaultDescription
enabledbooleantrueEnable the plugin.
servicestring | (params) => string—Override the service name. Pass a function to derive the name from connection parameters.
measuredboolean—Whether to measure the span for metrics.

​
PostgreSQL (pg)

const tracer = require('dd-trace').init()

tracer.use('pg', {
  // Fixed service name
  service: 'pg-primary',
  // Or derive from connection params
  // service: (params) => `pg-${params.database}`,

  // Database Monitoring propagation mode
  dbmPropagationMode: 'full',

  // Append rather than prepend the SQL comment
  appendComment: true
})
dbmPropagationMode correlates APM traces with Database Monitoring query samples. Valid values are 'disabled' (default), 'service', and 'full'.

​
MySQL and MySQL2

const tracer = require('dd-trace').init()

tracer.use('mysql', {
  service: (params) => `mysql-${params.database}`
})

tracer.use('mysql2', {
  service: 'mysql2-primary'
})
mariadb uses the same configuration interface as mysql.

​
MongoDB

The mongodb-core plugin instruments both the low-level mongodb-core driver and the mongodb package directly. The mongoose plugin provides additional Mongoose-specific spans. 
tracer.use('mongodb-core', {
  service: 'mongodb',
  // Include query in resource name for easier identification
  queryInResourceName: true
})

​
Redis

tracer.use('redis', {
  service: 'redis-cache',
  // Only instrument specific commands
  allowlist: ['get', 'set', 'del'],
  // Or exclude noisy commands
  blocklist: ['info', 'ping']
})
For Redis-family plugins, allowlist and blocklist filter by command name (lowercase), not by URL.

​
Elasticsearch and OpenSearch

tracer.use('elasticsearch', {
  service: 'elasticsearch',
  hooks: {
    query: (span, params) => {
      // params.method, params.path, params.body are available
      span.setTag('es.index', params.path.split('/')[1])
    }
  }
})

// opensearch uses the same interface as elasticsearch
tracer.use('opensearch', {
  service: 'opensearch'
})

​
OracleDB

tracer.use('oracledb', {
  service: (params) => `oracle-${params.connectString}`
})

​
Prisma

tracer.use('prisma', {
  // Configure client and engine instrumentation independently
  client: { service: 'prisma-client' },
  engine: true
})

​
Database Monitoring (DBM) integration

To correlate APM traces with Database Monitoring query samples, set dbmPropagationMode at the tracer level or per-plugin: 
const tracer = require('dd-trace').init({
  // Apply to all database plugins
  dbmPropagationMode: 'full'
})

// Or per plugin
tracer.use('pg', { dbmPropagationMode: 'full' })
ModeDescription
'disabled'No SQL comment injected (default).
'service'Injects service name only.
'full'Injects full trace context including trace and span IDs.

Build docs developers (and LLMs) love

Get started for freeTalk to us