Streaming StatsD Protocol Parser
raw JSON → 0.0.4 verified Thu Apr 23 auth: no javascript abandoned
statsd-parser is a Node.js library designed for streaming parsing of the StatsD protocol. It provides both a low-level `parser()` object for direct event-driven parsing and a higher-level `createStream()` API for integrating with Node.js streams, allowing for efficient processing of StatsD metrics from various input sources like network streams or files. The library was last updated in September 2013, with its current and only published version being 0.0.4. Due to its age and lack of maintenance for over a decade, it is not recommended for new projects or existing systems requiring modern Node.js compatibility, security updates, or active support. Key differentiators at the time of its release included its focus on streaming capabilities and event-driven parsing, which was beneficial for handling high-volume metric data efficiently in a Node.js environment.
Common errors
error TypeError: (intermediate value).parser is not a function ↓
cause Attempting to destructure `parser` or `createStream` from a CommonJS `require` call using ES Module syntax.
fix
Use the standard CommonJS pattern:
const statsd_parser = require('statsd-parser'); const parser = statsd_parser.parser(); error SyntaxError: Unexpected token 'export' ↓
cause Using `import statsd_parser from 'statsd-parser'` in an environment where `statsd-parser` is loaded as a CommonJS module and the bundler/runtime doesn't handle the interoperability.
fix
Change your import statement to
const statsd_parser = require('statsd-parser'); error Error: read ECONNRESET ↓
cause While not directly caused by `statsd-parser` itself, this error can occur when piping network streams (like UDP sockets) that abruptly close or reset the connection, which then affects the `statsd-parser` stream. This package's lack of updates means it won't have modern stream robustness features.
fix
Ensure the upstream network client or source sending data handles connection stability. For
statsd-parser, implement robust error handling on the stream (stream.on('error')) as shown in the quickstart, and consider using more modern, robust stream processing libraries or network handlers if connection issues are frequent. Warnings
breaking This package is critically unmaintained. The last publish was in 2013 (version 0.0.4) and there has been no development activity for over a decade. It may contain unpatched security vulnerabilities, is unlikely to be compatible with recent Node.js versions, and will not receive bug fixes or new features. ↓
fix Migrate to an actively maintained StatsD parsing library or a comprehensive observability solution. Examples include `node-statsd-client` (for sending), `telegraf` (for receiving/parsing as a daemon), or modern observability platforms like OpenTelemetry, Prometheus, or Datadog which often include robust StatsD parsing capabilities.
gotcha The package uses a CommonJS module system exclusively. Attempting to use `import` statements will result in runtime errors in environments that enforce ESM-only loading without CommonJS compatibility layers. ↓
fix Ensure you are using `require()` for importing the library in your Node.js application: `const statsd_parser = require('statsd-parser');`
gotcha Error handling for the `parser` object requires explicitly clearing the internal error state (`this._parser.error = null; this._parser.resume();`) within the `stream.on('error')` callback to prevent the stream from stopping after the first parsing error. Without this, a single malformed line can halt further processing. ↓
fix Implement the recommended error clearing and resumption logic within your `stream.on('error')` handler to maintain stream resilience:
```javascript
stream.on("error", function (e) {
console.error("Error parsing line:", e.message);
this._parser.error = null; // Clear internal parser error state
this._parser.resume(); // Allow parser to continue processing
});
```
Install
npm install statsd-parser yarn add statsd-parser pnpm add statsd-parser Imports
- statsd_parser wrong
import statsd_parser from 'statsd-parser';correctconst statsd_parser = require('statsd-parser'); - parser wrong
import { parser } from 'statsd-parser';correctconst statsd_parser = require('statsd-parser'); const parser = statsd_parser.parser(); - createStream wrong
import { createStream } from 'statsd-parser';correctconst statsd_parser = require('statsd-parser'); const stream = statsd_parser.createStream(options);
Quickstart
const statsd_parser = require("statsd-parser");
const fs = require('fs');
const { Readable } = require('stream');
// Basic parser usage
const parser = statsd_parser.parser();
parser.onerror = function (e) {
console.error("Parser Error:", e.message);
};
parser.onstat = function (txt, obj) {
console.log(`Parsed stat: ${txt} ->`, obj);
};
parser.onend = function () {
console.log("Basic parser stream finished.\n");
};
console.log("--- Using basic parser ---");
parser.write('foo.bar:1|c\nbaz.qux:2.5|g\n');
parser.write('timer.event:100|ms\n');
parser.close(); // Signal end of input
// Stream usage with a Readable stream
const stream = statsd_parser.createStream();
stream.on("error", function (e) {
console.error("Stream Error:", e.message);
// In a real application, you might need to handle this more robustly,
// like clearing the parser error and resuming if it's an internal parser error.
this._parser.error = null;
this._parser.resume();
});
stream.on("stat", function (txt, obj) {
console.log(`Streamed stat: ${txt} ->`, obj);
});
stream.on("end", () => {
console.log("Stream parser finished.");
});
console.log("--- Using stream parser ---");
const inputData = 'metric.one:10|c\nmetric.two:200|ms\nmetric.three:3.14|g\n';
const readableStream = Readable.from(inputData);
readableStream.pipe(stream);