Node.js StatsD Client (Legacy)

Common errors

• Error: Cannot find module 'node-statsd'

  cause The package is either not installed or there is a typo in the `require` path. Another common issue is attempting to `require` a package that only provides ESM exports, or vice-versa, though for this specific package, it's almost certainly a path/install issue or confusion with other StatsD clients.
  fix Ensure the package is installed via `npm install node-statsd`. Verify the `require` path is correct as `require('node-statsd')`. If using a modern Node.js environment, consider if you accidentally installed a different StatsD client or if your project configuration is mixing CJS/ESM.

• Error in socket: { [Error: send EPERM] code: 'EPERM' ... }

  cause The application's process lacks the necessary permissions to open or send data over a UDP socket, or a firewall is blocking the connection. This can also happen if the target host/port is unreachable or misconfigured.
  fix Check network connectivity to the StatsD host and port. Verify firewall rules allow UDP traffic on the specified port (default 8125). Ensure the user running the Node.js application has appropriate network permissions. Double-check `host` and `port` configuration options.

• TypeError: client.increment is not a function

  cause This usually indicates that `client` is not a valid `StatsD` instance, or the `require` statement failed. This can occur if the `node-statsd` package itself is corrupted or an incorrect module was loaded.
  fix Verify that `const StatsD = require('node-statsd');` executed successfully and `new StatsD()` returned an object. Check your `node_modules` directory for `node-statsd` to ensure it's correctly installed. Restart your application to clear any module cache issues.

Warnings

• breaking This `node-statsd` package (especially version 0.1.1) is exceptionally old and effectively abandoned. It is highly unlikely to be compatible with modern Node.js versions (v14+) or current best practices like ESM modules. Using it in new projects is strongly discouraged.
  Fix: Migrate to a currently maintained StatsD client library for Node.js, such as `hot-shots` or `statsd-client`. These alternatives offer better support for modern Node.js, ESM, and ongoing maintenance.
• gotcha The package uses UDP for sending metrics, which is an unreliable protocol. Messages are not guaranteed to be delivered, and data loss can occur, especially under network congestion or high load. StatsD is typically used for aggregate, non-critical metrics where some loss is acceptable.
  Fix: Be aware of UDP's inherent unreliability. For critical metrics requiring guaranteed delivery, StatsD (and by extension this client) is not the appropriate tool. Consider logging directly or using a reliable message queue.
• gotcha This client is exclusively CommonJS (`require`). It does not support ECMAScript Modules (ESM) syntax (`import`). Attempting to `import { StatsD } from 'node-statsd'` in an ESM context will result in a module resolution error.
  Fix: Ensure your project uses CommonJS `require()` for this package. If your project is ESM-first, you will need to use a CommonJS wrapper or, preferably, migrate to an ESM-compatible StatsD client.
• gotcha Error handling for network issues or failed metric submissions is manual. Socket errors must be caught by attaching a listener to the client's `socket` property, and message-specific errors are handled via callbacks on metric methods. Unhandled errors will bubble up and can crash the application.
  Fix: Always implement error listeners on `client.socket` and use the optional `callback` parameter for critical metric submissions to gracefully handle transmission errors.

Install

• npm install node-statsd npm
• yarn add node-statsd yarn
• pnpm add node-statsd pnpm

Imports

• StatsD
  wrong:

  const StatsD = require('node-statsd');

  correct:

  import { StatsD } from 'node-statsd';

  While this package, particularly in older versions like 0.1.1, primarily used CommonJS `require()`, modern Node.js environments typically use ESM `import`. However, this specific library is not designed for ESM and would likely only work via CommonJS `require` or with a transpiler.
• StatsD (CommonJS)

  const StatsD = require('node-statsd');

  This is the correct and primary way to import and use the `StatsD` client from this package, especially in older Node.js environments where it was developed. Attempting to use ESM `import` will likely fail.

Quickstart

Demonstrates initializing the StatsD client with optional parameters and sending various metric types like timing, increment, gauge, histogram, and set, including basic socket error handling.

const StatsD = require('node-statsd');
const client = new StatsD({
  host: process.env.STATSD_HOST ?? 'localhost',
  port: parseInt(process.env.STATSD_PORT ?? '8125', 10),
  prefix: 'my_app.',
  global_tags: ['env:development', 'service:backend']
});

// Timing: records the duration of an event in milliseconds
client.timing('api_response_time', 150.7, 0.5, ['endpoint:users', 'method:GET']);

// Increment: increments a counter by a value (default is 1)
client.increment('user_logins');
client.increment('failed_attempts', 5);

// Decrement: decrements a counter by a value (default is -1)
client.decrement('active_sessions');

// Gauge: sets a metric to an absolute value
client.gauge('current_memory_usage', process.memoryUsage().heapUsed / 1024 / 1024);

// Histogram: sends data for histogram stat
client.histogram('request_duration_ms', 250, 0.1);

// Set: counts unique occurrences of a stat
client.set('unique_visitors', 'user-abc-123');

// Error handling for the underlying socket
client.socket.on('error', (error) => {
  console.error('StatsD socket error:', error);
});

console.log('Metrics sent to StatsD (or attempted, check server logs).');