Awesome
DEPRECATED: promjs
A Prometheus metrics registry implemented in TypeScript
Goals
- Stick to Prometheus client best practices as closely as possible
- Run in Node.js or the browser
- Fit into the modern JavaScript ecosystem
- Minimally rely on third-party dependencies
Installation
Install via npm
:
$ npm install --save promjs
or via yarn
:
$ yarn add promjs
Usage
// Using es6 imports
import prom from 'promjs';
// Using CommonJS
const prom = require('promjs');
const registry = prom();
const pageRequestCounter = registry.create('counter', 'page_requests', 'A counter for page requests');
pageRequestCounter.inc();
console.log(registry.metrics());
// =>
// # HELP page_requests A counter for page requests \n
// # TYPE page_requests counter
// page_requests 1 \n
API
prom()
Returns a registry class.
Registry
registry.create(type, name, help) => collector (counter | gauge | histogram)
Returns a metric class of the specified type. The metric is already registered with the registry that creates it.
Arguments
type
(String): The type of metric to create. The current supported types arecounter
,gauge
, andhistogram
.name
(String): The name of the metrichelp
(String): The help message for the metric
Example
import prom from 'promjs';
const registry = prom();
const counter = registry.create('counter', 'my_counter', 'A counter for things');
registry.metrics() => string
Returns a prometheus formatted string containing all existing metrics.
const counter = registry.create('counter', 'my_counter', 'A counter for things');
counter.inc();
console.log(registry.metrics());
// =>
// # HELP my_counter A counter for things \n
// # TYPE my_counter counter
// my_counter 1 \n
registry.clear() => self
Removes all metrics from internal data
storage. Returns itself to allow for chaining.
registry.reset() => self
Resets all existing metrics to 0. This can be used to reset metrics after reporting to a prometheus aggregator. Returns itself to allow for chaining.
registry.get(type, name) => collector (counter | gauge | histogram) | null
Fetches an existing metric by name. Returns null if no metrics are found
Collector
All of the metric classes (Counter, Gauge, Histogram) inherit from the Collector class. Collector methods are available on each of the metic classes.
collector.reset([labels]) => self
Resets metrics in the collector. Optionally pass in labels to reset only those labels.
collector.resetAll() => self
Resets all metrics in the collector, including metrics with labels.
Counter
A counter can only ever be incremented positively.
counter.inc([labels]) => self
Increments a counter. Optionally pass in a set of labels to increment only those labels.
counter.add(amount, [labels]) => self
Increments a counter by a given amount. amount
must be a Number. Optionally pass in a set of labels to increment only those labels.
const counter = registry.create('counter', 'my_counter', 'A counter for things');
counter.inc();
counter.add(2, { ok: true, status: 'success', code: 200 });
counter.add(2, { ok: false, status: 'fail', code: 403 });
console.log(registry.metrics());
// =>
// # HELP my_counter A counter for things
// # TYPE my_counter counter
// my_counter 1
// my_counter{ok="true",status="success",code="200"} 2
// my_counter{ok="false",status="fail",code="403"} 2
Gauge
A gauge is similar to a counter, but can be incremented up and down.
gauge.inc([labels]) => self
Increments a gauge by 1.
gauge.dec([lables]) => self
Decrements a gauge by 1.
gauge.add(amount, [lables]) => self
Increments a gauge by a given amount. amount
must be a Number.
gauge.sub(amount, [labels]) => self
Decrements a gauge by a given amount.
const gauge = registry.create('gauge', 'my_gauge', 'A gauge for stuffs');
gauge.inc();
gauge.inc({ instance: 'some_instance' });
gauge.dec({ instance: 'some_instance' });
gauge.add(100, { instance: 'some_instance' });
gauge.sub(50, { instance: 'some_instance' });
console.log(registry.metrics());
// =>
// # HELP my_gauge A gauge for stuffs
// # TYPE my_gauge gauge
// my_gauge 1
// my_gauge{instance="some_instance"} 50
Histogram
Histograms are used to group values into pre-defined buckets. Buckets are passed in to the registry.create()
call.
histogram.observe(value) => self
Adds value
to a pre-existing bucket.value
must be a number.
const histogram = registry.create('histogram', 'response_time', 'The response time', [
200,
300,
400,
500
]);
histogram.observe(299);
histogram.observe(253, { path: '/api/users', status: 200 });
histogram.observe(499, { path: '/api/users', status: 200 });
console.log(registry.metrics());
// =>
// # HELP response_time The response time
// # TYPE response_time histogram
// response_time_count 3
// response_time_sum 599
// response_time_bucket{le="200"} 1
// response_time_bucket{le="400",path="/api/users",status="200"} 1
// response_time_bucket{le="200",path="/api/users",status="200"} 1
Getting Help
If you have any questions about, feedback for or problems with promjs
:
- Invite yourself to the <a href="https://slack.weave.works/" target="_blank">Weave Users Slack</a>.
- Ask a question on the #general slack channel.
- File an issue.
Weaveworks follows the CNCF Code of Conduct. Instances of abusive, harassing, or otherwise unacceptable behavior may be reported by contacting a Weaveworks project maintainer, or Alexis Richardson (alexis@weave.works).
Your feedback is always welcome!