Popularity
1.3
Stable
Activity
9.4
Growing
50
7
1

Programming language: TypeScript
License: MIT License
Latest version: v1.0.0

dats alternatives and similar modules

Based on the "Debugging / Profiling" category.
Alternatively, view dats alternatives based on common mentions on social networks and blogs.

Do you think we are missing an alternative of dats or a related project?

Add another 'Debugging / Profiling' Module

README

dats

release workflow code style: prettier semantic-release npm (scoped) license

Minimalistic zero-dependencies UDP/TCP statsd client for Node.js

There are times when you have to gather metrics and you want something simple without writing too much boilerplate, dats to your aid!

This client aims to have a simple statsd compliant API with some optional flavour for advanced usage, like: buffered metrics and either UDP/TCP transports!

Table of Content

<!-- toc -->

<!-- tocstop -->

Installation

The package is available at npm.

You can install it with npm

# lastest stable version
$ npm i -S @immobiliarelabs/dats
# latest development version
$ npm i -S @immobiliarelabs/[email protected]

or yarn

# lastest stable version
$ yarn add @immobiliarelabs/dats
# latest development version
$ yarn @immobiliarelabs/[email protected]

Usage

Generic

import Client from '@immobiliarelabs/dats';

const stats = new Client({
    host: 'udp://someip:someport',
    namespace: 'myGrafanaNamespace',
    // Optionally register a global handler to track errors.
    onError: (error) => {
        processError(error);
    },
});

// Send counter (myGrafanaNamespace.some.toCount)
stats.counter('some.toCount', 3);
stats.counter('some.toCount'); // defaults to 1
stats.counter('some.toCount', 1, 10); // set sampling to 10
// Send timing (myGrafanaNamespace.some.toTime)
stats.timing('some.toTime', 10);
stats.timing('some.toTime', 10, 0.1); // set sampling to 0.1

// Send gauge (myGrafanaNamespace.some.toGauge)
stats.gauge('some.toGauge', 23);

// Send set (myGrafanaNamespace.some.set)
stats.set('some.set', 765);

Namespacing with Hostname/PID

// Scope your stats per hostname and/or pid
import Client from '@immobiliarelabs/dats';

const stats = new Client({
    host: 'udp://someip:someport',
    namespace: 'myGrafanaNamespace.${hostname}.${pid}',
});

// Send counter (myGrafanaNamespace.myMachine.123.some.toCount)
stats.counter('some.toCount', 3);

If the hostname contains any ., the client will replace them with _.

TCP Client

import Client from '@immobiliarelabs/dats';

// TCP usage
const stats = new Client({
    host: 'tcp://someip:someport',
    namespace: 'myGrafanaNamespace.${hostname}.${pid}',
});

// Calling connect is required in TCP environment
await stats.connect();

// Send counter (myGrafanaNamespace.myMachine.123.some.toCount)
stats.counter('some.toCount', 3);

API

This module exports:

Client

The statsd client

new Client(options)

  • options: configuration object.
    • host: statsd host (udp://{ip}:{port} or tcp://{ip}:{port}), you can use also ipv6. If you want to force udp6 usage use: udp6://{host}:{port}, when using TCP, you have to call the Client.connect method.
    • namespace: Optional. Prefix to use for the metrics. The metric will be sent as namespace. + the metric string. Optionally you can use ${hostname} and ${pid} placeholders in the namespace and have them substituted with the machine hostname and the process id.
    • bufferSize: Optional. Default is 0. Setting this value to a number greather than zero will activate buffered mode, which instead of sending metrics on each call, it will buffer them and send them when one of this conditions occurs: the buffer is full, or the bufferFlushTimeout has expired. Using this approach is more performant, but you must be careful to use a value compatible to the MTU available on your network, otherwise your packets might get dropped silently. See multi-metric-packets.
    • bufferFlushTimeout: Optional. Default is 100. Timeout in milliseconds to wait before flushing the metrics buffer.
    • debug: Optional. Default debuglog('dats'). The logger function.
    • udpDnsCache: Optional. Default true. Activate the cache DNS lookup for udp.
    • udpDnsCacheTTL: Optional. Default 120. Dns cache Time to live in seconds.
    • onError: Optional. Default (err) => void. Called when there is an error. Allows you to check also send errors.

Client.close([cb])

close the client socket

  • cb: optional. A callback function to call when the socket is closed. If no cb is provided a Promise is returned.

Returns: a Promise if no cb is passed.

Client.connect()

connect the TCP socket. Calling this function is required only on TCP.

Returns: a Promise.

Client.counter(string[, value, sampling])

send a metric of type counter

  • string: The metric string
  • value: Optional. The metric value (Number). Defaults to 1.
  • sampling: Optional. The metric sampling.

All sending errors are handled by the onError callback.

Client.timing(string, value[, sampling])

send a metric of type timing

  • string: The metric string
  • value: The metric value (Number).
  • sampling: Optional. The metric sampling.

All sending errors are handled by the onError callback.

Client.gauge(string, value)

send a metric of type gauge

  • string: The metric string
  • value: The metric value (Number).

All sending errors are handled by the onError callback.

Client.set(string, value)

send a metric of type set

  • string: The metric string
  • value: The metric value (Number).

All sending errors are handled by the onError callback.

Benchmarks

The tests were done using autocannon pointing to an HTTP node.js Server that sends at each request a count metric. With this kind of test, we evaluate how much the library influences the application performance.

Below are reported the benchmarks with the most famous node.js statsd clients:

LIBRARY Req/Sec (97.5th) Req/Sec (avg)
dats 45503 43174.4
hot-shots 46975 43319.47
node-statsd 14935 11632.34
statsd-client 42463 35790.67
Base 50271 43312.54

Base is the HTTP server without metrics.

Powered Apps

dats was created by the amazing Node.js team at ImmobiliareLabs, the Tech dept of Immobiliare.it, the #1 real estate company in Italy.

We are currently using dats in our products as well as our internal toolings.

If you are using dats in production drop us a message.

Support & Contribute

Made with โค๏ธ by ImmobiliareLabs & [Contributors](./CONTRIBUTING.md#contributors)

We'd love for you to contribute to dats! If you have any questions on how to use dats, bugs and enhancement please feel free to reach out by opening a GitHub Issue.

License

dats is licensed under the MIT license.
See the [LICENSE](./LICENSE) file for more information.


*Note that all licence references and agreements mentioned in the dats README section above are relevant to that project's source code only.