README.md

inspector-prometheus

Typescript metric reporter for prometheus.

This library is made for inspector-metrics node module and is meant to be used with nodejs.

All metrics from the inspector-metrics library can be pushed to a pushgateway or be exposed with a custom /metrics endpoint in your application.

Take a look at the Documentation.

install

npm install --save inspector-prometheus

basic usage

example.ts

import {
    MetricRegistry,
} from "inspector-metrics";

import {
    PrometheusMetricReporter,
} from "inspector-prometheus";

// contains all metrics
const registry = new MetricRegistry();
// exposes the metrics
const reporter = new PrometheusMetricReporter({});

// register the registry within the reporter
reporter.addMetricRegistry(registry);

// common tags for all metrics
const tags = new Map();
tags.set("app_version", "1.0.0");
reporter.setTags(tags);

// a simple request timer used to report response latencies
const requests: Timer = registry.newTimer("requests");
// custom metric tag
requests.setTag("host", "127.0.0.3");

// some server implementation - could be anything KOA, Express, HAPI ...
const server = new Hapi.Server({ host: "0.0.0.0", port: 8080 });

// '/metrics' is the standard route used by prometheus ...
server.route({
    method: "GET",
    path: "/metrics",
    handler(request, h) {
        console.log("reporting metrics");
        return h.response(reporter.getMetricsString())
            .code(200)
            .type("text/plain");
    },
});

// starts the server
server.start();

/etc/prometheus/config.yml

global:
  scrape_interval:     15s
  evaluation_interval: 30s

scrape_configs:
- job_name: test-app
  metrics_path: /metrics
  static_configs:
    - targets:
      - localhost:8080

example metrics report

# HELP requests request durations for some endpoint
# TYPE requests summary
requests{app_version="1.0.0",host="127.0.0.3",quantile="0.01"} 0
requests{app_version="1.0.0",host="127.0.0.3",quantile="0.05"} 0
requests{app_version="1.0.0",host="127.0.0.3",quantile="0.5"} 999936
requests{app_version="1.0.0",host="127.0.0.3",quantile="0.75"} 999936
requests{app_version="1.0.0",host="127.0.0.3",quantile="0.9"} 1000192
requests{app_version="1.0.0",host="127.0.0.3",quantile="0.95"} 1000192
requests{app_version="1.0.0",host="127.0.0.3",quantile="0.98"} 1999872
requests{app_version="1.0.0",host="127.0.0.3",quantile="0.99"} 2000128
requests{app_version="1.0.0",host="127.0.0.3",quantile="0.999"} 4000000
requests_count{app_version="1.0.0",host="127.0.0.3"} 362
requests_sum{app_version="1.0.0",host="127.0.0.3"} 283998208

reporting options for PrometheusMetricReporter

import {
    PrometheusMetricReporter,
} from "inspector-prometheus";

const reporter = new PrometheusMetricReporter({
    includeTimestamp: true,
    emitComments: true,
    useUntyped: false,
});

multi process support (nodejs cluster)

Due to the nature of prometheus scraping multiple processes need to collect
metrics in order report all metrics of every process.

Therefore the PrometheusMetricReporter implements an internal
request/response mechanism to gather all metrics from all forked processes
and wait for the response before serving all metrics data.

You should set the pid as reporter tag to be able to determine
between the multiple metrics sources.

Only the master process should serve the metrics to the prometheus server.

import * as cluster from "cluster";

import {
    tagsToMap,
} from "inspector-metrics";

import {
    PrometheusMetricReporter,
} from "inspector-prometheus";

const reporter = new PrometheusMetricReporter({});

// set "pid" to process id
reporter.setTags(tagsToMap({
    pid: `${process.pid}`,
}));

if (cluster.isMaster) {
    // some server implementation - could be anything KOA, Express, HAPI ...
    const server = new Hapi.Server({ host: "0.0.0.0", port: 8080 });

    // '/metrics' is the standard route used by prometheus ...
    server.route({
        method: "GET",
        path: "/metrics",
        handler(request, h) {
            console.log("reporting metrics");
            return h.response(reporter.getMetricsString())
                .code(200)
                .type("text/plain");
        },
    });

    // starts the server
    server.start();
}

report metrics with pushgateway

import ...; // like in the example above

import {
    PrometheusMetricReporter,
    PushgatewayMetricReporter,
} from "inspector-prometheus";

// contains all metrics
const registry = new MetricRegistry();
// exposes the metrics
const reporter = new PrometheusMetricReporter({});

// register the registry within the reporter
reporter.addMetricRegistry(registry);

const pushReporter = new PushgatewayMetricReporter({
    reporter,

    host: "localhost",
    port: 9091,
    job: "pushgateway",
    instance: "127.0.0.4",
});

// start reporting
await pushReporter.start();

multi process support (nodejs cluster)

By default cluster support is disabled for PushgatewayMetricReporter.
You should set the pid as reporter tag.

import {
    tagsToMap,
} from "inspector-metrics";

import {
    PrometheusMetricReporter,
    PushgatewayMetricReporter,
} from "inspector-prometheus";

const reporter = new PrometheusMetricReporter({});
const pushReporter = new PushgatewayMetricReporter({
    reporter,
    ...
});

// set "pid" to process id
reporter.setTags(tagsToMap({
    pid: `${process.pid}`,
}));

// start reporting
await pushReporter.start();

License

MIT