# statsd-client

> Yet another client for Etsy's statsd

Latest version **0.4.7** (published 2021-06-03) · MIT license · 0 weekly downloads

> **Deprecated.** This package is deprecated.

## Install

```sh
npm install statsd-client
pnpm add statsd-client
yarn add statsd-client
bun add statsd-client
```

## Health

**Score 10/100 (F)** — status: deprecated.

Negative: deprecated.

## Facts

| | |
|---|---|
| Version | 0.4.7 |
| Published | 2021-06-03 |
| First published | 2012-05-23 |
| Weekly downloads | 0 |
| License | MIT |
| TypeScript types | separate (@types/statsd-client) |
| Module format | CommonJS |
| Dependencies | 0 |
| Unpacked size | 57 KB |
| Known vulnerabilities | 0 |
| Install scripts | no |
| GitHub stars | 169 |
| Author | Morten Siebuhr |
| Maintainers | papandreou, msiebuhr |
| Keywords | statsd, client, metrics, udp, tcp |

## Links

- npm: https://www.npmjs.com/package/statsd-client
- Repository: https://github.com/msiebuhr/node-statsd-client
- Issues: https://github.com/msiebuhr/node-statsd-client/issues
- npm.io page: https://npm.io/package/statsd-client

## Alternatives

- [launchdarkly-js-client-sdk](https://npm.io/package/launchdarkly-js-client-sdk.md) — 2.5M weekly downloads
- [@elastic/elasticsearch](https://npm.io/package/@elastic/elasticsearch.md) — 2.1M weekly downloads
- [@c8y/client](https://npm.io/package/@c8y/client.md) — 15.3K weekly downloads
- [@signaldb/maverickjs](https://npm.io/package/@signaldb/maverickjs.md) — 1.7K weekly downloads
- [@bbc/http-transport-cache](https://npm.io/package/@bbc/http-transport-cache.md) — 1.2K weekly downloads

## Recent versions

- 0.4.7 (latest) — 2021-06-03
- 0.4.6 — 2021-04-22
- 0.4.5 — 2020-07-08
- 0.4.4 — 2019-09-26
- 0.4.3 — 2019-09-26
- 0.4.2 — 2018-02-01
- 0.4.1 — 2018-01-31
- 0.4.0 — 2017-06-30
- 0.3.0 — 2017-05-31
- 0.2.4 — 2016-11-25
- 0.2.3 — 2016-11-08
- 0.2.2 — 2016-03-17
- 0.2.1 — 2015-10-27
- 0.2.0 — 2015-08-25
- 0.1.0 — 2015-03-02
- … 19 more at https://npm.io/package/statsd-client/versions

## README

node-statsd-client
==================

Node.js client for [statsd](https://github.com/etsy/statsd).

[![Build Status](https://secure.travis-ci.org/msiebuhr/node-statsd-client.png?branch=master)](http://travis-ci.org/msiebuhr/node-statsd-client)

Quick tour
----------

```javascript
var SDC = require('statsd-client'),
	sdc = new SDC({host: 'statsd.example.com'});

var timer = new Date();
sdc.increment('some.counter'); // Increment by one.
sdc.gauge('some.gauge', 10); // Set gauge to 10
sdc.timing('some.timer', timer); // Calculates time diff
sdc.histogram('some.histogram', 10, {foo: 'bar'}) // Histogram with tags
sdc.distribution('some.distribution', 10, {foo: 'bar'}) // Distribution with tags

sdc.close(); // Optional - stop NOW
```

API
---

### Initialization

```javascript
var SDC = require('statsd-client'),
	sdc = new SDC({host: 'statsd.example.com', port: 8124});
```

Global options:
 * `prefix`: Prefix all stats with this value (default `""`).
 * `tcp`: User specifically wants to use tcp (default `false`).
 * `socketTimeout`: Dual-use timer. Will flush metrics every interval. For UDP,
   it auto-closes the socket after this long without activity (default 1000 ms;
   0 disables this). For TCP, it auto-closes the socket after `socketTimeoutsToClose` number of timeouts have elapsed without activity.
 * `tags`: Object of string key/value pairs which will be appended on to all StatsD payloads (excluding raw payloads) (default `{}`)

UDP options:
 * `host`: Where to send the stats (default `localhost`).
 * `port`: Port to contact the statsd-daemon on (default `8125`).
 * `ipv6`: Use IPv6 instead of IPv4 (default `false`).

TCP options:
 * `host`: Where to send the stats (default `localhost`).
 * `port`: Port to contact the statsd-daemon on (default `8125`).
 * `socketTimeoutsToClose`: Number of timeouts in which the socket auto-closes if it has been inactive. (default `10`; `1` to auto-close after a single timeout).

HTTP options:
 * `host`: The URL to send metrics to (default: `http://localhost`).
 * `headers`: Additional headers to send (default `{}`)
 * `method`: What HTTP method to use (default `PUT`)

To debug, set the environment variable `NODE_DEBUG=statsd-client` when running your program.

### Counting stuff

Counters are supported, both as raw `.counter(metric, delta)` and with the
shortcuts `.increment(metric, [delta=1])` and `.decrement(metric, [delta=-1])`:

```javascript
sdc.increment('systemname.subsystem.value'); // Increment by one
sdc.decrement('systemname.subsystem.value', -10); // Decrement by 10
sdc.counter('systemname.subsystem.value', 100); // Increment by 100
```

### Gauges

Sends an arbitrary number to the back-end:

```javascript
sdc.gauge('what.you.gauge', 100);
sdc.gaugeDelta('what.you.gauge', 20);  // Will now count 120
sdc.gaugeDelta('what.you.gauge', -70); // Will now count 50
sdc.gauge('what.you.gauge', 10);       // Will now count 10
```

### Sets

Send unique occurences of events between flushes to the back-end:

```javascript
sdc.set('your.set', 200);
```

### Delays

Keep track of how fast (or slow) your stuff is:

```javascript
var start = new Date();
setTimeout(function () {
	sdc.timing('random.timeout', start);
}, 100 * Math.random());
```

If it is given a `Date`, it will calculate the difference, and anything else
will be passed straight through.

And don't let the name (or nifty interface) fool you - it can measure any kind
of number, where you want to see the distribution (content lengths, list items,
query sizes, ...)

### Histogram

Many implementations (though not the official one from Etsy) support
histograms as an alias/alternative for timers. So aside from the fancy bits
with handling dates, this is much the same as `.timing()`.

### Distribution

Datadog's specific implementation supports another alternative to timers/histograms,
called the [distribution metric type](https://docs.datadoghq.com/metrics/distributions/).
From the client's perspective, this is pretty much an alias to histograms and can be used via `.distribution()`.

### Raw

Passes a raw string to the underlying socket. Useful for dealing with custom
statsd-extensions in a pinch.

```javascript
sdc.raw('foo.bar:123|t|@0.5|#key:value');
```

### Tags

All the methods above support metric level tags as their last argument. Just like global tags, the format for metric tags is an object of string key/value pairs.
Tags at the metric level overwrite global tags with the same key.

```javascript
sdc.gauge('gauge.with.tags', 100, {foo: 'bar'});
```

### Express helper

There's also a helper for measuring stuff in [Express.js](http://expressjs.com)
via middleware:

```javascript
var SDC = require('statsd-client');
var app = express();
	sdc = new SDC({...});

app.use(sdc.helpers.getExpressMiddleware('somePrefix'));
// or
app.get('/',
	sdc.helpers.getExpressMiddleware('otherPrefix'),
	function (req, res, next) { req.pipe(res); });

app.listen(3000);
```

This will count responses by status-code (`prefix.<statuscode>`) and the
overall response-times.

It can also measure per-URL (e.g. PUT to `/:user/:thing` will become
`PUT_user_thing` by setting the `timeByUrl: true` in the `options`-object:

```javascript
app.use(sdc.helpers.getExpressMiddleware('prefix', { timeByUrl: true }));
```

As the names can become rather odd in corner-cases (esp. regexes and non-REST
interfaces), you can specify another value by setting `res.locals.statsdUrlKey`
at a later point.

The `/` page will appear as `root` (e.g. `GET_root`) in metrics while any not found route will appear as `{METHOD}_unknown_express_route`. You can change that name by setting the `notFoundRouteName` in the middleware options.


### Callback helper

There's also a helper for measuring stuff with regards to a callback:

```javascript
var SDC = requrire('statsd-client');
	sdc = new SDC({...});

function doSomethingAsync(arg, callback) {
	callback = sdc.helpers.wrapCallback('somePrefix', callback);
	// ... do something ...
	return callback(null);
}
```

The callback is overwritten with a shimmed version that counts the
number of errors (`prefix.err`) and successes (`prefix.ok`) and
the time of execution of the function (`prefix.time`).
You invoked the shimmed callback exactly the same way as though
there was no shim at all. Yes, you get metrics for your function in
a single line of code.

Note that the start of execution time is marked as soon as you
invoke `sdc.helpers.wrapCallback()`.

You can also provide more options:

```javascript
sdc.helpers.wrapCallback('somePrefix', callback, {
	tags: { foo: 'bar' }
});
```

### Stopping gracefully

By default, the socket is closed if it hasn't been used for a second (see
`socketTimeout` in the init-options), but it can also be force-closed with
`.close()`:

```javascript
var start = new Date();
setTimeout(function () {
	sdc.timing('random.timeout', start); // 2 - implicitly re-creates socket.
	sdc.close(); // 3 - Closes socket after last use.
}, 100 * Math.random());
sdc.close(); // 1 - Closes socket early.
```

The call is idempotent, so you can call it "just to be sure". And if you submit
new metrics later, the socket will automatically be re-created, and a new
timeout-timer started.

### Prefix-magic

The library supports getting "child" clients with extra prefixes, to help with
making sane name-spacing in apps:

```javascript
// Create generic client
var sdc = new StatsDClient({host: 'statsd.example.com', prefix: 'systemname'});
sdc.increment('foo'); // Increments 'systemname.foo'
... do great stuff ...

// Subsystem A
var sdcA = sdc.getChildClient('a');
sdcA.increment('foo'); // Increments 'systemname.a.foo'

// Subsystem B
var sdcB = sdc.getChildClient('b');
sdcB.increment('foo'); // Increments 'systemname.b.foo'
```

Internally, they all use the same socket, so calling `.close()` on any of them
will allow the entire program to stop gracefully.

What's broken
-------------

Check the [GitHub issues](https://github.com/msiebuhr/node-statsd-client/issues).

Other resources
---------------

 * [statsd-tail](https://github.com/msiebuhr/statsd-tail) - A simple program to grab statsd-data on localhost
 * [hot-shots](https://www.npmjs.com/package/hot-shots) - Another popular statsd client for Node.js
 * [statsd](https://github.com/etsy/statsd) - The canonical server

RELEASES
--------

See the [changelog](CHANGELOG.md).

LICENSE
-------

ISC - see
[LICENSE](https://github.com/msiebuhr/node-statsd-client/blob/master/LICENSE).

---
_Source: https://npm.io/package/statsd-client · Machine-readable twin of the npm.io package page. Health data is recomputed on every publish._