@metrics/client

A streaming metric producer. Allows producing counters, gauges, time series in a way that is independent of your metrics system so that you can produce metrics and let consumers decide how to consume them. Additionally, you can pipe together different metrics streams before finally consuming them all in a single location.

Quick start

The client is intended to be used in the following way:

Step 1.

Instantiate a new client

const client = new Metrics();

Step 2.

Use the client for instrumentation

const counter = client.counter({
    name: 'unique_metric_name',
    description: 'Description of metric being collected',
});

counter.inc();

Step 3.

Pipe collected metrics to a collector

client.pipe(consumer);

The client supports 4 types of metric creation use cases.

Counters are supported via the client.counter method
Gauges are supported via the client.gauge method
Histograms are supported via the client.histogram method
Summaries are supported via the client.summary method

Examples

Creating and incrementing a counter

const counter = client.counter({
    name: 'my_counter',
    description: 'Counter description',
});
counter.inc();

Creating and incrementing a gauge

const gauge = client.gauge({
    name: 'my_gauge',
    description: 'Gauge description',
});
gauge.set(10);

Creating and incrementing a summary

const summary = client.summary({
    name: 'my_summary',
    description: 'Summary description',
});
summary.observe(0.123);

Creating and incrementing a summary using a timer

const summary = client.summary({
    name: 'my_summary',
    description: 'Summary description',
});
const end = summary.timer();
// ... time something
end();

Creating and incrementing a histogram

const histogram = client.histogram({
    name: 'my_histogram',
    description: 'Histogram description',
});
histogram.observe(0.123);

Creating and incrementing a histogram using a timer

const histogram = client.histogram({
    name: 'my_histogram',
    description: 'Histogram description',
});
const end = histogram.timer();
// ... time something
end();

Composing metric streams

One of the goals of @metrics/client is to allow any number of modules to produce their own metrics, not know about where they might be consumed.

This can be achieved by including and instantiating a @metrics/client client in each module, using it to create metrics and then exposing the client for consumption elsewhere.

Example

// module-1

const Metrics = require('@metrics/client');
const client = new Metrics();

const counter = client.counter({
    name: 'my_counter',
    description: 'Counter description',
});
counter.inc();

module.exports.metrics = client;

// module-2

const Metrics = require('@metrics/client');
const client = new Metrics();

const counter = client.counter({
    name: 'my_counter',
    description: 'Counter description',
});
counter.inc();

module.exports.metrics = client;

// consuming module
const module1 = require('module-1');
const module2 = require('module-2');
const consumer = require('some-consumer');

module1.pipe(consumer);
module2.pipe(consumer);

Metrics consumption

In order to consume metrics produced by @metrics/client you just need to listen for data and use your favourite metrics client to convert our data format into something usable by your system of choice.

Example: Prometheus using prom-client

const { Counter } = require('prom-client');
const { Writable } = require('stream');

class Consumer extends Writable {
    constructor() {
        super({ objectMode: true });

        this.counter = new Counter({
            name: 'my_metric_counter',
            help: 'Counts http request type things',
            labelNames: ['url', 'method'],
        });
    }

    _write(metric, enc, cb) {
        let url;
        let method;

        metric.labels.forEach(obj => {
            if (obj.name === 'url') {
                url = obj.value;
            }
            if (obj.name === 'method') {
                url = obj.value;
            }
        });

        this.counter.labels(url, method).inc(1);
        cb();
    }
}

API

new Metrics(options)

Creates a new instance of the metrics client.

The Metrics instance inherit from Transform Stream. Due to this the instance also take all config parameters which the Transform Stream does. Please see the documentation of Transform Streams for further documentation.

options

name	description	type	default
`id`	A optional unique identifier of the instance of the Object.	`string`	hash

Example

const client = new Metrics(options);

return: Duplex Stream

instance methods

.counter(options)

Creates an instance of a Counter class which can be used to populate the metrics stream with counter metrics.

options

name	description	type	default	required
`name`	Metric name. valid characters: a-z,A-Z,0-9,_	`string`	null	`true`
`description`	Metric description	`string`	null	`true`
`labels`	Available to be used to hold label data.	`object`	null	`false`

return: Counter

Example

const client = new Metrics(options);
const counter = client.counter(options);

counter.inc(value|options, options)

Method that when called will populate the metrics stream with a counter increment.

name	description	type	default	required
`value`	Value to increment the counter by	`integer`	`1`	`false`
`options`	Object that can be used to specify labels	`object`	`{}`	`false`

Example

const counter = client.counter(options);

counter.inc(); // increment by 1
counter.inc(10); // increment by 10
counter.inc({ labels: { url: 'http://finn.no' } }); // increment by 1, specify labels
counter.inc(5, { labels: { url: 'http://finn.no' } }); // increment by 5, specify labels

.gauge(options)

Creates an instance of a Gauge class which can be used to populate the metrics stream with gauge metrics.

options

name	description	type	default	required
`name`	Metric name. valid characters: a-z,A-Z,0-9,_	`string`	null	`true`
`description`	Metric description	`string`	null	`true`
`labels`	Available to be used to hold label data.	`object`	null	`false`

Example

const client = new Metrics(options);
const gauge = client.gauge(options);

gauge.set(value, options)

Method that when called will populate the metrics stream with a gauge value.

name	description	type	default	required
`value`	Value to set the gauge to	`integer`	null	`true`
`options`	Object that can be used to specify labels	`object`	`{}`	`false`

Example

const gauge = client.gauge(options);

gauge.set(10); // set to 10
gauge.set(5, { labels: { url: 'http://finn.no' } }); // set to 5, specify labels

.histogram(options)

Creates an instance of a Histogram class which can be used to populate the metrics stream with histogram metrics.

options

name	description	type	default	required
`name`	Metric name. valid characters: a-z,A-Z,0-9,_	`string`	null	`true`
`description`	Metric description	`string`	null	`true`
`meta`	Available to be used to hold any misc data.	`object`	null	`false`
`labels`	Available to be used to hold label data.	`object`	null	`false`

Example

const client = new Metrics(options);
const histogram = client.histogram(options);

histogram.observe(value, options)

Method that when called will populate the metrics stream with a histogram value.

name	description	type	default	required
`value`	Value to set the gauge to	`integer`	null	`true`
`options`	Object that can be used to specify labels and meta	`object`	`{}`	`false`

Example

const histogram = client.histogram(options);

histogram.observe(0.001); // observe value 0.001
histogram.observe(5, { labels: { url: 'http://finn.no' } }); // observe value 5, specify labels
histogram.observe(0.01, {
    meta: { buckets: [0.0001, 0.001, 0.01, 0.1, 0.5, 1, 10, 100] }, // observe 0.01, use meta to specify bucket options
});

histogram.timer(options)

Method that when called will return an end function for use in measuring the time between 2 points

name	description	type	default	required
`options`	Object that can be used to specify labels and meta	`object`	`{}`	`false`

Examples

const histogram = client.histogram(options);

const end = histogram.timer(); // start timer
// stuff happens
end();

const end = histogram.timer({ labels: { url: 'http://finn.no' } }); // start timer, set labels
// stuff happens
end();

const end = histogram.timer(); // start timer
// stuff happens
end({ labels: { url: 'http://finn.no' } }); // set labels in end function

const end = histogram.timer(meta: { buckets: [0.0001, 0.001, 0.01, 0.1, 0.5, 1, 10, 100] }); // start timer, set meta
// stuff happens
end();

.summary(options)

Creates an instance of a Summary class which can be used to populate the metrics stream with summary metrics.

options

name	description	type	default	required
`name`	Metric name. valid characters: a-z,A-Z,0-9,_	`string`	null	`true`
`description`	Metric description	`string`	null	`true`
`meta`	Available to be used to hold any misc data.	`object`	null	`false`
`labels`	Available to be used to hold label data.	`object`	null	`false`

Example

const client = new Metrics(options);
const summary = client.summary(options);

summary.observe(value, options)

Method that when called will populate the metrics stream with a summary value.

name	description	type	default	required
`value`	Value to set the summary to	`integer`	null	`true`
`options`	Object that can be used to specify labels and meta	`object`	`{}`	`false`

Example

const summary = client.summary(options);

summary.observe(0.001); // observe value 0.001
summary.observe(5, { labels: { url: 'http://finn.no' } }); // observe value 5, specify labels
summary.observe(0.01, {
    meta: { quantiles: [0.001, 0.01, 0.5, 0.9, 0.99] }, // observe 0.01, use meta to specify quantile meta
});

summary.timer(options)

Method that when called will return an end function for use in measuring the time between 2 points

name	description	type	default	required
`options`	Object that can be used to specify labels and meta	`object`	`{}`	`false`

Examples

const summary = client.summary(options);

const end = summary.timer(); // start timer
// stuff happens
end();

const end = summary.timer({ labels: { url: 'http://finn.no' } }); // start timer, set labels
// stuff happens
end();

const end = summary.timer(); // start timer
// stuff happens
end({ labels: { url: 'http://finn.no' } }); // set labels in end function

const end = summary.timer({
    meta: { quantiles: [0.001, 0.01, 0.5, 0.9, 0.99] },
}); // start timer, set meta
// stuff happens
end();

.metric(options)

Collects a generic metric. As a minimum, a name and description for the metric must be provided.

options

name	description	type	default	required
`name`	Metric name. valid characters: a-z,A-Z,0-9,_	`string`	null	`true`
`description`	Metric description	`string`	null	`true`
`value`	Arbitrary value for the metric (used for gauges)	`string\|number`	null	`false`
`meta`	Available to be used to hold any misc data.	`object`	null	`false`
`labels`	Available to be used to hold label data.	`array[object]`	null	`false`

return: void

client.metric({
    name: '',
    description: '',
});

meta

meta can be used to hold any additional information you might wish to pass on to a consumer. It should be an object of keys and values.

client.metric({
    name: 'my_metric',
    description: 'My HTTP timing metric',
    meta: {
        quantiles: [0.01, 0.1, 0.5, 0.9, 0.99],
    },
});

labels

labels can be used to pass on specific label metadata to a consumer. Examples of labels are the URL or method when timing HTTP requests.

Labels should be defined as an array of objects where each object has a name and value property. The name property describes the labels name and the value property describes the label's actual value.

client.metric({
    name: 'my_metric',
    description: 'My HTTP timing metric',
    labels: [
        { name: 'url', value: 'http://finn.no' },
        { name: 'method', value: 'get' },
    ],
});

.timer(options)

Starts a metric timer and returns and end function to be called when the measurement should be considered finished.

options

name	description	type	default	required
`name`	Metric name. valid characters: a-z,A-Z,0-9,_	`string`	null	`true`
`description`	Metric description	`string`	null	`true`
`value`	Arbitrary value for the metric (used for gauges)	`string\|number`	null	`false`
`meta`	Available to be used to hold any misc data	`object`	null	`false`

return: function Returns an end function (see below) to be used to indicate that the timer measurement is finished.

Example

const end = client.timer(options);

.end(options)

Stops a previously started timer, merges timers options with end options and and sets the measured time value.

options

name	description	type	default	required
`name`	Metric name. valid characters: a-z,A-Z,0-9,_	`string`	null	`true`
`description`	Metric description	`string`	null	`true`
`value`	Arbitrary value for the metric (used for gauges)	`string\|number`	null	`false`
`meta`	Available to be used to hold any misc data	`object`	null	`false`

return: void

Example

const end = client.timer(options);
// ... thing to be measured
end(options);

instance events

drop

Emitted when the client starts dropping metrics. Will emit the dropped metric.

Example

const client = new Metrics();
client.on('drop', metric => {
    console.log('dropped metric', metric);
});

Name		Name	Last commit message	Last commit date
Latest commit History 63 Commits
benchmark		benchmark
lib		lib
test		test
.eslintignore		.eslintignore
.eslintrc		.eslintrc
.gitignore		.gitignore
.npmrc		.npmrc
.prettierignore		.prettierignore
.prettierrc		.prettierrc
.travis.yml		.travis.yml
CHANGELOG.md		CHANGELOG.md
LICENSE		LICENSE
PULL_REQUEST_TEMPLATE		PULL_REQUEST_TEMPLATE
README.md		README.md
package.json		package.json

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!

Repository files navigation

@metrics/client

Quick start

Step 1.

Step 2.

Step 3.

Examples

Composing metric streams

Metrics consumption

API

new Metrics(options)

instance methods

.counter(options)

counter.inc(value|options, options)

.gauge(options)

gauge.set(value, options)

.histogram(options)

histogram.observe(value, options)

histogram.timer(options)

.summary(options)

summary.observe(value, options)

summary.timer(options)

.metric(options)

.timer(options)

.end(options)

instance events

drop

About

Uh oh!

Releases 5

Uh oh!

Contributors 10

Uh oh!

Languages

License

metrics-js/client

Folders and files

Latest commit

History

Repository files navigation

@metrics/client

Quick start

Step 1.

Step 2.

Step 3.

Examples

Composing metric streams

Metrics consumption

API

new Metrics(options)

instance methods

.counter(options)

counter.inc(value|options, options)

.gauge(options)

gauge.set(value, options)

.histogram(options)

histogram.observe(value, options)

histogram.timer(options)

.summary(options)

summary.observe(value, options)

summary.timer(options)

.metric(options)

.timer(options)

.end(options)

instance events

drop

About

Topics

Resources

License

Uh oh!

Stars

Watchers

Forks

Releases 5

Uh oh!

Contributors 10

Uh oh!

Languages