{"id":14757,"library":"node-statsd","title":"Node.js StatsD Client (Legacy)","description":"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.","status":"abandoned","version":"0.1.1","language":"javascript","source_language":"en","source_url":"git://github.com/sivy/node-statsd","tags":["javascript"],"install":[{"cmd":"npm install node-statsd","lang":"bash","label":"npm"},{"cmd":"yarn add node-statsd","lang":"bash","label":"yarn"},{"cmd":"pnpm add node-statsd","lang":"bash","label":"pnpm"}],"dependencies":[],"imports":[{"note":"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.","wrong":"const StatsD = require('node-statsd');","symbol":"StatsD","correct":"import { StatsD } from 'node-statsd';"},{"note":"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.","symbol":"StatsD (CommonJS)","correct":"const StatsD = require('node-statsd');"}],"quickstart":{"code":"const StatsD = require('node-statsd');\nconst client = new StatsD({\n  host: process.env.STATSD_HOST ?? 'localhost',\n  port: parseInt(process.env.STATSD_PORT ?? '8125', 10),\n  prefix: 'my_app.',\n  global_tags: ['env:development', 'service:backend']\n});\n\n// Timing: records the duration of an event in milliseconds\nclient.timing('api_response_time', 150.7, 0.5, ['endpoint:users', 'method:GET']);\n\n// Increment: increments a counter by a value (default is 1)\nclient.increment('user_logins');\nclient.increment('failed_attempts', 5);\n\n// Decrement: decrements a counter by a value (default is -1)\nclient.decrement('active_sessions');\n\n// Gauge: sets a metric to an absolute value\nclient.gauge('current_memory_usage', process.memoryUsage().heapUsed / 1024 / 1024);\n\n// Histogram: sends data for histogram stat\nclient.histogram('request_duration_ms', 250, 0.1);\n\n// Set: counts unique occurrences of a stat\nclient.set('unique_visitors', 'user-abc-123');\n\n// Error handling for the underlying socket\nclient.socket.on('error', (error) => {\n  console.error('StatsD socket error:', error);\n});\n\nconsole.log('Metrics sent to StatsD (or attempted, check server logs).');","lang":"javascript","description":"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."},"warnings":[{"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.","message":"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.","severity":"breaking","affected_versions":"<=1.0.4"},{"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.","message":"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.","severity":"gotcha","affected_versions":">=0.1.1"},{"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.","message":"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.","severity":"gotcha","affected_versions":">=0.1.1"},{"fix":"Always implement error listeners on `client.socket` and use the optional `callback` parameter for critical metric submissions to gracefully handle transmission errors.","message":"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.","severity":"gotcha","affected_versions":">=0.1.1"}],"env_vars":null,"last_verified":"2026-04-19T00:00:00.000Z","next_check":"2026-07-18T00:00:00.000Z","problems":[{"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.","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.","error":"Error: Cannot find module 'node-statsd'"},{"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.","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.","error":"Error in socket: { [Error: send EPERM] code: 'EPERM' ... }"},{"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.","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.","error":"TypeError: client.increment is not a function"}],"ecosystem":"npm"}