# numbat-emitter

> numbat-powered metrics emitter

Latest version **5.2.4** (published 2020-10-16) · ISC license · 0 weekly downloads

## Install

```sh
npm install numbat-emitter
pnpm add numbat-emitter
yarn add numbat-emitter
bun add numbat-emitter
```

## Health

**Score 15/100 (F)** — status: abandoned.

Positive: no vulnerabilities.

Warnings: low downloads; no types; no esm support.

Negative: abandoned; low maintenance score.

## Facts

| | |
|---|---|
| Version | 5.2.4 |
| Published | 2020-10-16 |
| First published | 2014-06-09 |
| Weekly downloads | 0 |
| License | ISC |
| TypeScript types | none |
| Module format | CommonJS |
| Dependencies | 6 |
| Unpacked size | 46.7 KB |
| Known vulnerabilities | 0 (+1 in 1 direct dependencies) |
| Install scripts | no |
| GitHub stars | 18 |
| Author | C J Silverio |
| Maintainers | jar349, npm-qa-tfa2, npm-qa-tfa1, kmm745, npm-qa, ndorfman, mylesborins, t-dedim, t-dekell, mikkeljuhl, anywherepilot, yujincat, jp-andre, jmoody, smeirsha, radiantspace, stoneman, baj-, kc15155, avocaddo, ethomson, ajaykn, olefriis, owenniblock, maxxkrakoa, christoflemke, hilli, gordey4doronin, jacobe, sapieneptus, meijin007, lumaxis, soph2k, phillipleblanc, john7doe, robdnpm, anthonywcheng, npm-sre-write, npm-sre-readonly, mangwana, ruyadorno, darcyclarke, kh5127, gar, thedave42, andrialexandrou, andreeleuterio, isaacs, npm, bonkydog, npmci, lisayu, nlf, adam_baldwin, aearly, ceejbot, mmalecki, chrisdickinson, buzuli, soldair |
| Keywords | influxdb, metrics, monitoring, numbat |

## Links

- npm: https://www.npmjs.com/package/numbat-emitter
- Repository: https://github.com/numbat-metrics/numbat-emitter
- Issues: https://github.com/numbat-metrics/numbat-emitter/issues
- npm.io page: https://npm.io/package/numbat-emitter

## Dependencies (6)

- [ws](https://npm.io/package/ws.md) ^5.1.1
- [lodash](https://npm.io/package/lodash.md) ^4.17.10
- [request](https://npm.io/package/request.md) ^2.88.0
- [squeaky](https://npm.io/package/squeaky.md) ^2.4.2
- [discard-stream](https://npm.io/package/discard-stream.md) ^1.0.1
- [readable-stream](https://npm.io/package/readable-stream.md) ^2.3.6

## Recent versions

- 5.2.4 (latest) — 2020-10-16
- 5.2.3 — 2020-07-10
- 5.2.2 — 2020-05-07
- 5.2.1 — 2018-10-17
- 5.2.0 — 2018-10-17
- 5.1.2 — 2018-10-17
- 5.1.1 — 2018-10-10
- 5.1.0 — 2018-10-10
- 5.0.2 — 2018-05-16
- 5.0.1 — 2018-01-24
- 5.0.0 — 2018-01-22
- 4.0.1 — 2017-07-28
- 4.0.0 — 2017-04-11
- 3.2.1 — 2016-09-27
- 3.2.0 — 2016-07-07
- … 22 more at https://npm.io/package/numbat-emitter/versions

## README

# numbat-emitter

[Numbat](http://www.arkive.org/numbat/myrmecobius-fasciatus/)-powered metrics emitter. See [numbat-collector](https://github.com/numbat-metrics/numbat-collector) for the matching metrics collector.

[![on npm](http://img.shields.io/npm/v/numbat-emitter.svg?style=flat)](https://www.npmjs.org/package/numbat-emitter)  [![Tests](http://img.shields.io/travis/numbat-metrics/numbat-emitter.svg?style=flat)](http://travis-ci.org/numbat-metrics/numbat-emitter) [![Coverage Status](https://coveralls.io/repos/github/numbat-metrics/numbat-emitter/badge.svg?branch=master)](https://coveralls.io/github/numbat-metrics/numbat-emitter?branch=master) [![Dependencies](http://img.shields.io/david/numbat-metrics/numbat-emitter.svg?style=flat)](https://david-dm.org/numbat-metrics/numbat-emitter)

## Example

```javascript
var Emitter = require('numbat-emitter');

var emitter = new Emitter({
    uri: 'tcp://localhost:8000',
    app: 'www',
    node: 'www:8081'
});
emitter.metric({ name: 'httpd.latency', value: 30 });
emitter.metric({ name: 'disk.used.percent', value: 36 });
emitter.metric({ name: 'heartbeat'});

// if you don't have a reference to an emitter, you
// can broadcast a metric to a global emitter:
Emitter.setGlobalEmitter(emitter);
process.emit('metric', { name: 'heartbeat' });
```

See the `examples/` directory for working examples.

## Configuration

The constructor requires an options object with an app name in the `app` field and some manner of specifying where to emit the metrics. You can specify the protocol, host, and port in handy url-parseable format: `tcp://collector.example.com:5000`, `udp://localhost:5000`, `socket:/tmp/foozle.sock`, `ws://localhost:5000`, `nsq://nsqd.example.com:4151`, `statsd://statsd.example.com:8125` Do this in the `uri` field of the options object.

Config options:

| option | description | required? | default |
|--------|-------------|-----------|---------|
| uri    | uri of the metrics collector | either this or path | |
| path   | path to the unix domain socket where the collector is listening | either this or uri ||
| app    | name of this service or app; every metric name will be prefixed with it | y | |
| node   | name of this specific app instance |  | |
| maxretries | number of times to retry connecting before giving up |  | 100 |
| maxbacklog | max number of metrics to hold in backlog during reconnects | | 1000 |
| shouldUnref | should numbat avoid holding the process open if its the only active conn? | | true |


An example:

```javascript
{
    uri:  'udp://localhost:8000',
    app: 'udp-emitter',
    node: 'emitter-1',
    maxretries: 10,
    maxbacklog: 200,
}
```

Or numbat might be listening via a unix domain socket:

```javascript
{
    path: '/tmp/numbat-collector.sock',
    app: 'socket-emitter'
}
```

For complete working emitters, see the [examples directory](examples/).

## Events

Valid events look like this:

```javascript
{
    name: 'name.of.metric',
    value: 42
    status: 'okay' | 'warning' | 'critical' | 'unknown',
    description: 'textual description',
    ttl: ms-to-live,
    // fields provided for you
    app: 'appname-from-options',
    host: os.hostname(),
    time: ts-in-ms,
}
```

You can add any fields you like & they will be persisted in InfluxDB. However, only the fields listed above are meaningful to the analyzer. Those fields are described in detail below.

NOTE: You can of course emit any events you like! The style of events required/expected by numbat's [analyzer](https://github.com/ceejbot/numbat-analyzer), however, might change in development.

### name

String. Required. Name of this event or metric. Use dots `.` to separate namespaces. If you do not prefix the metric name with `yourapp.`, numbat will do this for you.

### time

Number. Optional. Timestamp in milliseconds since the epoch. If you do not pass a time field, one will be created for you with `Date.now()`.

### value

Number. Optional. The value of this metric, if appropriate. If you do not pass a value field, it will be defaulted to `1`.

### status

String. Optional. One of `okay`, `warning`, `critical`, or `unknown`. Use this to trigger alerts if this event represents a known-bad condition.

### description

Textual description of the event. Max 255 bytes. Optional.

### ttl

Number. Optional. Milliseconds that this event is considered valid. The analyzer will expire the event after `event.time` + `event.ttl`.

## Practical event examples

See also the example emitter in [example.js](./example.js).

```javascript
var e1 = {
    name: 'request.latency',
    value: 42
    status: 'okay',
};
var e2 = {
    name: 'request.latency',
    value: 5023
    status: 'warning',
};

var e3 = { name: 'heartbeat', ttl: 30000 };
```

## Contributing

Yes, please do! See our [contributing guide](https://github.com/numbat-metrics/documentation/blob/master/contributing.md) for basic rules of engagement.

## License

[ISC](http://opensource.org/licenses/ISC)

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