The DogStatsD client is available as tracer.dogstatsd. It sends custom metrics to the Datadog Agent over UDP using the DogStatsD protocol.
const tracer = require('dd-trace').init()
const { dogstatsd } = tracer
TracerOptions:
const tracer = require('dd-trace').init({
dogstatsd: {
hostname: '127.0.0.1', // DD_DOGSTATSD_HOST
port: 8125, // DD_DOGSTATSD_PORT
},
})
// Object format (recommended)
{ method: 'GET', status: '200', service: 'api' }
// Array format
['method:GET', 'status:200', 'service:api']
TracerOptions.tags.
Methods
Increments a metric by the specified value.
increment(stat: string, value?: number, tags?: Record<string, string|number> | string[]): void
The dot-separated metric name (e.g., http.requests).
The amount to increment by. Defaults to 1.
Tags to attach to this metric submission.
// Increment by 1 (default)
tracer.dogstatsd.increment('http.requests')
// Increment by a specific value with tags
tracer.dogstatsd.increment('http.requests', 1, { method: 'GET', status: '200' })
// Array tag format
tracer.dogstatsd.increment('http.requests', 1, ['method:GET', 'status:200'])
Decrements a metric by the specified value.
decrement(stat: string, value?: number, tags?: Record<string, string|number> | string[]): void
The dot-separated metric name.
The amount to decrement by. Defaults to 1.
Tags to attach to this metric submission.
tracer.dogstatsd.decrement('active.connections')
tracer.dogstatsd.decrement('active.connections', 1, { pool: 'primary' })
Sets a gauge to the specified value. A gauge represents the current value of a metric at a point in time.
gauge(stat: string, value?: number, tags?: Record<string, string|number> | string[]): void
The dot-separated metric name.
Tags to attach to this metric submission.
tracer.dogstatsd.gauge('queue.depth', 42)
tracer.dogstatsd.gauge('memory.usage', process.memoryUsage().heapUsed, { service: 'worker' })
Records a value in a histogram. Histograms track the statistical distribution of a set of values and compute percentiles, average, max, and sum.
histogram(stat: string, value?: number, tags?: Record<string, string|number> | string[]): void
The dot-separated metric name.
Tags to attach to this metric submission.
const start = Date.now()
await processRequest()
const duration = Date.now() - start
tracer.dogstatsd.histogram('request.duration', duration, {
route: '/api/users',
method: 'GET',
})
Records a value in a distribution metric. Distributions are similar to histograms but are aggregated globally on the Datadog backend (rather than per-host), making them ideal for distributed systems.
distribution(stat: string, value?: number, tags?: Record<string, string|number> | string[]): void
The dot-separated metric name.
Tags to attach to this metric submission.
tracer.dogstatsd.distribution('api.response_time', responseTimeMs, {
endpoint: '/users',
region: 'us-east-1',
})
flush()
Forces any unsent metrics to be flushed immediately.
This method is experimental and may be removed in future versions.
// Flush before process shutdown
process.on('beforeExit', () => {
tracer.dogstatsd.flush()
})
Full example
const tracer = require('dd-trace').init()
const { dogstatsd } = tracer
app.use((req, res, next) => {
const start = Date.now()
// Track active requests
dogstatsd.increment('http.active_requests', 1, { method: req.method })
res.on('finish', () => {
const duration = Date.now() - start
const tags = {
method: req.method,
status: String(res.statusCode),
route: req.route?.path ?? 'unknown',
}
dogstatsd.increment('http.requests', 1, tags)
dogstatsd.histogram('http.response_time', duration, tags)
dogstatsd.decrement('http.active_requests', 1, { method: req.method })
})
next()
})
