Node.js Datadog StatsD Client

0.0.7 · abandoned · verified Sun Apr 19

node-dogstatsd is an unmaintained Node.js client specifically designed for Datadog's extended StatsD server, differentiating itself from generic StatsD clients by supporting Datadog-specific features like histograms and tags. The package's current stable version is 0.0.7, indicating a very old codebase. It was initially an extension of Steve Ivy's `node-statsd`, adding Datadog's proprietary features. Given its version number and engine requirements (Node.js >=0.1.97), it is largely incompatible with modern Node.js environments and ecosystems. There is no active release cadence, and the project appears to be abandoned, making it unsuitable for new development. Its core utility lies in providing an API to send metrics, timings, and custom events with tags and histograms to a Datadog agent.

Common errors

```
TypeError: Cannot read properties of undefined (reading 'StatsD')
```
cause The package's main export is an object, and the `StatsD` class is a property of that object. Attempting to `require('node-dogstatsd')` without accessing `.StatsD` will result in this error.

fix Correct the import statement to `const StatsD = require('node-dogstatsd').StatsD;`
```
Error: send EPIPE
```
cause This error typically indicates an issue with the underlying UDP socket, such as the Datadog agent not running, incorrect host/port configuration, or network connectivity problems preventing the client from sending data.

fix Verify that the Datadog agent is running and accessible at the specified `host` and `port`. Check network connectivity and firewall rules. Implement `c.socket.on('error', ...)` to catch and handle these exceptions gracefully.
```
npm WARN node-dogstatsd@0.0.7 requires a peer of node@>=0.1.97 but none is installed.
```
cause The package specifies an extremely old Node.js version requirement, which is incompatible with modern Node.js installations, leading to npm warnings or installation failures.

fix This warning signifies severe version incompatibility. It is highly recommended to abandon this package and migrate to a modern Datadog client library that supports your current Node.js version.

Warnings

breaking This package specifies `engines: {"node": ">=0.1.97"}`, making it incompatible with modern Node.js versions. Attempting to install or run it on recent Node.js environments will likely result in errors or undefined behavior.
Fix: Do not use this package for new projects. Consider actively maintained alternatives like `@datadog/dogstatsd` or `dd-trace` for modern Node.js applications.
gotcha The `histogram` and `tags` features provided by this client are specific to Datadog's extended StatsD implementation. These features will not function correctly with generic StatsD servers and may lead to data loss or silent failures if used outside a Datadog ecosystem.
Fix: Ensure you are using a Datadog agent that supports the extended StatsD protocol when utilizing histograms and tags. For generic StatsD, use a standard StatsD client.
breaking The package is severely outdated (version 0.0.7, last updated around Node.js 0.1 era) and appears to be unmaintained. This poses significant security risks, lacks support for modern features, and will not receive critical bug fixes.
Fix: This package should be considered a legacy dependency. Migrate to a modern and actively maintained Datadog client library as soon as possible.
gotcha The README explicitly states "Error handling policy: TODO" regarding documenting exceptions, implying that the library's error handling might be incomplete or poorly defined, potentially leading to unhandled exceptions that could crash the application.
Fix: Implement robust socket error handling using `c.socket.on('error', function(exception){ ... });` and monitor for unexpected application crashes related to metric submission.

Install

npm install node-dogstatsd npm
yarn add node-dogstatsd yarn
pnpm add node-dogstatsd pnpm

Imports

StatsD
wrong:
```
import { StatsD } from 'node-dogstatsd';
```
correct:
```
const StatsD = require('node-dogstatsd').StatsD;
```
This package exclusively uses CommonJS `require` syntax. The `StatsD` class is a named export from the main module.

Quickstart

This quickstart demonstrates how to initialize the `node-dogstatsd` client and send various metric types including increments, timings, histograms, and tagged metrics to a Datadog agent, along with basic socket error handling.

const StatsD = require('node-dogstatsd').StatsD;

// Initialize the client with your Datadog agent host and port
// Replace '127.0.0.1' with your Datadog agent's IP or hostname
// Standard StatsD port is 8125
const c = new StatsD('127.0.0.1', 8125);

// Basic increment and decrement operations
c.increment('node_test.requests_total');
c.incrementBy('node_test.requests_total', 5);
c.decrement('node_test.active_users');

// Record a timing metric (e.g., latency in milliseconds)
c.timing('node_test.api_response_time', 250); // 250 ms

// Record a histogram metric (Datadog-specific)
// Useful for percentile aggregation
c.histogram('node_test.data_processing_size', 1024); // Size in bytes

// Increment a metric with a specific tag (Datadog-specific)
c.increment('node_test.event_count', 1, ['environment:production', 'feature:login']);

// Listen for socket errors (recommended for robustness)
c.socket.on('error', function (exception) {
   console.error("Error event in socket.send(): " + exception.message);
   // Implement proper error handling here, e.g., logging to a file or an error tracking service
});

console.log("Datadog metrics sent successfully (check your Datadog agent logs for verification).");
// In a real application, metrics would typically be sent throughout the application's lifecycle.

view raw JSON →