node-statsd

library0.1.1jsnpmunverified

This entry describes `node-statsd`, a client library for sending metrics to a StatsD server from Node.js applications. The specific version provided, 0.1.1, is exceptionally old, predating the 1.0.0 release. The package allows sending common StatsD metric types such as timings, increments, decrements, histograms, and gauges over UDP. It offers basic configuration for host, port, prefix, suffix, and optional global tags. Due to its age (last significant update over 7 years ago, with the provided version being even older), this client is considered largely abandoned. Modern Node.js applications should consider more actively maintained alternatives like `hot-shots` or `statsd-client` which offer broader compatibility, better error handling, and more features. The release cadence for this specific package is effectively non-existent.

observability

npm install node-statsd

github ↗package ↗

INSTALL

IMPORT

SIG · NODE-STATSD

node-statsd

observabilityjavascriptv0.1.1

Install

—

Import

—

Disk

—

Pass rate

0/ 6

Env Coverage0 / 6

glibc

18–22

musl

18–22

Install & Compatibility

Where this runs

tested against v? · npm install

Install × environment matrix

Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux

musl

node 18–226 runs

build_error

glibc

node 18–226 runs

build_error

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

StatsD

✓ import { StatsD } from 'node-statsd';

✗ const StatsD = require('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.

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).');

Debug

Known issues

breakingThis `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.

affects: <=1.0.4

gotchaThe 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.

affects: >=0.1.1

gotchaThis 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.

affects: >=0.1.1

gotchaError 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.

affects: >=0.1.1

Errors

Common errors & fixes

Error: Cannot find module 'node-statsd'

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' ... }

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

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.

Upgrade

Version history

0.1.1latest on npm

Audit

Dependencies

No dependency data recorded yet.

Agent activity

10 hits · last 30 days

node

OpenAI (training)

Resources

githubhttps://github.com/sivy/node-statsd ↗

packagehttps://www.npmjs.com/package/node-statsd ↗