Documentation Index
Fetch the complete documentation index at: https://mintlify.com/datadog/dd-trace-js/llms.txt
Use this file to discover all available pages before exploring further.
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()
})
