mrfranke / promjs Goto Github PK

A Prometheus metrics registry implemented in TypeScript

• 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

Install via npm:

$ npm install --save promjs

or via yarn:

$ yarn add promjs

// 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

Returns a registry class.

Returns a metric class of the specified type. The metric is already registered with the registry that creates it.

Arguments

1. type (String): The type of metric to create. The current supported types are counter, gauge, and histogram.
2. name (String): The name of the metric
3. help (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');

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

Removes all metrics from internal data storage. Returns itself to allow for chaining.

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.

Fetches an existing metric by name. Returns null if no metrics are found

All of the metric classes (Counter, Gauge, Histogram) inherit from the Collector class. Collector methods are available on each of the metic classes.

Resets metrics in the collector. Optionally pass in labels to reset only those labels.

Resets all metrics in the collector, including metrics with labels.

A counter can only ever be incremented positively.

Increments a counter. Optionally pass in a set of labels to increment only those labels.

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

A gauge is similar to a counter, but can be incremented up and down.

Increments a gauge by 1.

Decrements a gauge by 1.

Increments a gauge by a given amount. amount must be a Number.

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

Histograms are used to group values into pre-defined buckets. Buckets are passed in to the registry.create() call.

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

If you have any questions about, feedback for or problems with promjs:

• Invite yourself to the Weave Users Slack.
• 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 ([email protected]).

Your feedback is always welcome!