[译]Prometheus监控NodeJS SDK(prom-client)使用说明

github地址：https://github.com/siimon/prom-client

（此文为尚不熟悉时所译，如有错误烦请指出修改）

Readme：

这是一个支持histogram, summaries, gauges and counters四种数值格式的prometheus nodejs客户端。

用法

在example文件夹中有用法示例。这个库不会绑定任何web框架，只会在registry中返回metrics()函数来显示metrics。

通过nodejs的cluster模式使用

nodejs的cluster模式产生了多进程并且不会干涉socket连接其他workers。从一个worker的本地registry返回metrics只会显示那个worker自己的metrics，这一般是不可取的。为了解决这点，你可以在主进程合并所有worker的metrics。查看example/cluster.js获取示例。

默认的metrics使用合理的聚合方法。自定义metrics默认会按照workers求和。要使用不同的合并方法，需要在metric配置中设置aggregator属性为'sum', 'first', 'min', 'max', 'average' or 'omit'的其中一个。（查看lib/metrics/version.js获取示例。）

如果你想要显示一个worker的metrics，可以包含一个只属于这个worker的值（比如worker ID或者进程ID）在标签中。（查看example/server.js获取使用worker_${cluster.worker.id}作为标签值的示例。）

metrics默认会通过全局registry来聚合。要使用不同的registry，就在worker进程中调用client.AggregatorRegistry.setRegistries(registryOrArrayOfRegistries)。

API

配置

所有的metrics类型都有两个强制的参数：name和help。

默认metrics

有一些Prometheus自身推荐的默认metrics。要采集这些，就调用collectDefaultMetrics

注意：有些metrics，关于文件描述符和内存的，只在Linux可获取。

此外，包含了一些node特有的metrics，比如事件循环滞后（ event loop lag），active handles和nodejs版本。在 lib/metrics 查看有哪些metrics。

collectDefaultMetrics 获取一个有三个条目的选项对象，一个指定探测多久执行一次的timeout参数，一个表示metric名称的可选前缀和一个表示哪个metrics需要被注册的注册器。默认为每10秒探测一次，但这可以像这样修改：

const client = require('prom-client');

const collectDefaultMetrics = client.collectDefaultMetrics;

// Probe every 5th second.
collectDefaultMetrics({ timeout: 5000 });

注册metrics到其他注册器，传递一个注册器进来：

const client = require('prom-client');

const collectDefaultMetrics = client.collectDefaultMetrics;
const Registry = client.Registry;
const register = new Registry();

collectDefaultMetrics({ register });

传入一个前缀来以任意字符串作为metrics前缀名：

const client = require('prom-client');

const collectDefaultMetrics = client.collectDefaultMetrics;

// Probe every 5th second.
collectDefaultMetrics({ prefix: 'my_application_' });

你可以通过检查client.collectDefaultMetrics.metricsList来获取metrcis的所有条目。

collectDefaultMetrics 会在调用时返回一个身份标识，这是一个依赖于Timer的，用来保持探测进行。要停止所有的探测，可以传入clearInterval 。

注意：现有的间隔会在调用collectDefaultMetrics时自动清除。

const client = require('prom-client');

const collectDefaultMetrics = client.collectDefaultMetrics;

const interval = collectDefaultMetrics();

// ... some time later

clearInterval(interval);

注意：unref 会在interval 内部调用，所以它不会在作为唯一保持避免停止的程序时保持你的node进程运行。

停止轮询默认metrics

要停止采集默认metrics，你需要调用调用函数并传给clearInterval。

const client = require('prom-client');

clearInterval(client.collectDefaultMetrics());

// Clear the register
client.register.clear();

Counter数值

Counter会持续增长，并在进程重启时重置。

const client = require('prom-client');
const counter = new client.Counter({
  name: 'metric_name',
  help: 'metric_help'
});
counter.inc(); // Inc with 1
counter.inc(10); // Inc with 10

Gauge数值

Gauge类似Counter，但Gauge值可以减少。

const client = require('prom-client');
const gauge = new client.Gauge({ name: 'metric_name', help: 'metric_help' });
gauge.set(10); // Set to 10
gauge.inc(); // Inc with 1
gauge.inc(10); // Inc with 10
gauge.dec(); // Dec with 1
gauge.dec(10); // Dec with 10

有一些公用的工具案例：

gauge.setToCurrentTime(); // Sets value to current time

const end = gauge.startTimer();
xhrRequest(function(err, res) {
  end(); // Sets value to xhrRequests duration in seconds
});

Histogram数值

Histogram追踪事件的尺寸和频率

配置

默认的桶用来覆盖常规的web/rpc请求，但这可以被覆写。

const client = require('prom-client');
new client.Histogram({
  name: 'metric_name',
  help: 'metric_help',
  buckets: [0.1, 5, 15, 50, 100, 500]
});

你也可以包含所有的标签名作为属性。

const client = require('prom-client');
new client.Histogram({
  name: 'metric_name',
  help: 'metric_help',
  labelNames: ['status_code'],
  buckets: [0.1, 5, 15, 50, 100, 500]
});

示例

const client = require('prom-client');
const histogram = new client.Histogram({
  name: 'metric_name',
  help: 'metric_help'
});
histogram.observe(10); // Observe value in histogram

观察请求时间的工具

const end = histogram.startTimer();
xhrRequest(function(err, res) {
  end(); // Observes the value to xhrRequests duration in seconds
});

Summary数值

Summary用来计算观察值的百分数。

配置
默认百分数为0.01, 0.05, 0.5, 0.9, 0.95, 0.99, 0.999。但他们可以这样改写：

const client = require('prom-client');
new client.Summary({
  name: 'metric_name',
  help: 'metric_help',
  percentiles: [0.01, 0.1, 0.9, 0.99]
});

为了确保summary的滑动窗口功能，你需要像这样在配置中添加maxAgeSeconds 和ageBuckets ：

const client = require('prom-client');
new client.Summary({
  name: 'metric_name',
  help: 'metric_help',
  maxAgeSeconds: 600,
  ageBuckets: 5
});

maxAgeSeconds会指定一个bucket多久之后会重置，ageBuckets指定在我们的summary滑动窗口中有多少buckets。

使用示例:

const client = require('prom-client');
const summary = new client.Summary({
  name: 'metric_name',
  help: 'metric_help'
});
summary.observe(10);

用来观察请求周期：

const end = summary.startTimer();
xhrRequest(function(err, res) {
  end(); // Observes the value to xhrRequests duration in seconds
});

Labels

所有的metrics都可以在配置对象中设置一个标签名属性。所有metric支持的标签名都需要在这申明。有两个方法来添加标签：

const client = require('prom-client');
const gauge = new client.Gauge({
  name: 'metric_name',
  help: 'metric_help',
  labelNames: ['method', 'statusCode']
});

gauge.set({ method: 'GET', statusCode: '200' }, 100); // 1st version, Set value 100 with method set to GET and statusCode to 200
gauge.labels('GET', '200').set(100); // 2nd version, Same as above

也可能通过标签使用计时器，在即使前前后都会创建：

const end = startTimer({ method: 'GET' }); // Set method to GET, we don't know statusCode yet
xhrRequest(function(err, res) {
  if (err) {
    end({ statusCode: '500' }); // Sets value to xhrRequest duration in seconds with statusCode 500
  } else {
    end({ statusCode: '200' }); // Sets value to xhrRequest duration in seconds with statusCode 200
  }
});

默认标签（按注册器分割）
静态的标签可能应用于一个注册器下的每个metric：

const client = require('prom-client');
const defaultLabels = { serviceName: 'api-v1' };
client.register.setDefaultLabels(defaultLabels);

这会按下面的方式输出所有metrics:

# HELP process_resident_memory_bytes Resident memory size in bytes.
# TYPE process_resident_memory_bytes gauge
process_resident_memory_bytes{serviceName="api-v1"} 33853440 1498510040309

默认标签的名称如果重复了，会被覆写。

register.clear()会清除默认标签。

时间戳

Counter和Gauge metrics可以在值参数后接收一个时间戳参数。这个参数必须是一个Date或者一个数字（milliseconds since Unix epoch, i.e. 1970-01-01 00:00:00 UTC，不计跳跃秒数）。

gauge.set(100, 1485531442231); // Set gauge value and timestamp as milliseconds since Unix epoch
gauge.set(100, Date.now()); // Set gauge value and timestamp as milliseconds since Unix epoch
gauge.set(100, new Date()); // Set gauge value and timestamp as Date
gauge.set({ method: 'GET', statusCode: '200' }, 100, new Date()); // Set gauge value and timestamp with labels
gauge.labels('GET', '200').set(100, new Date()); // Same as above

counter.inc(1, new Date()); // Increment counter with timestamp

多注册器

默认情况下，metrics是自动注册到全局注册器（require('prom-client').register）的。你可以在创建metric时通过设置最后一个参数为false（依赖于metric，这可能是第四或第五个参数）来避免这样做。

使用非全局注册器需要创建注册器实例并添加它到配置对象的registers中。或者你可以传入一个空registers数组并手动去注册它。

注册器有一个merge函数可以用来在同一个端点暴露多个注册器。如果同一个metric名在不同注册器中存在，会抛出一个错误。

const client = require('prom-client');
const registry = new client.Registry();
const counter = new client.Counter({
  name: 'metric_name',
  help: 'metric_help',
  registers: [registry]
});
const histogram = new client.Histogram({
  name: 'metric_name',
  help: 'metric_help',
  registers: []
});
registry.registerMetric(histogram);
counter.inc();

const mergedRegistries = client.Registry.merge([registry, client.register]);

如果你想要在nodejs cluster模式下使用多个或非默认注册器，需要设置注册器合并：

const AggregatorRegistry = client.AggregatorRegistry;
AggregatorRegistry.setRegistries(registry);
// or for multiple registries:
AggregatorRegistry.setRegistries([registry1, registry2]);

注册器

你可以通过运行register.metrics()获取所有的metrics，这会输出一个字符串给prometheus。

register.metrics()接受一个时间戳范围的可选对象。将之设为false会将字符串的时间戳去除。

获取单个metric供prometheus展示

如果你需要输出单个metric给prometheus，可以使用register.getSingleMetricAsString(name of metric)，这会输出一个字符串给prometheus。

获取单个metric

如果你需要获取一个之前注册的metric，可以使用register.getSingleMetric(name of metric)。

移除metrics

你可以调用register.clear()移除所有metrics。还可以调用register.removeSingleMetric(name of metric)移除单个metric。

重置metrics
如果你需要重置所有metrics，可以使用register.resetMetrics()。这些metrics会保留在注册器中，并无需再次实例化它们就能使用，但在register.clear()之后你需要实例化。

Cluster metrics

你可以在nodejs cluster中通过register.clusterMetrics()获取所有workers的聚合metrics。该方法返回一个promise并接收一个callback，这两者都解决一个适合传给prometheus的metrics字符串。

register
  .clusterMetrics()
  .then(metrics => {
    /* ... */
  })
  .catch(err => {
    /* ... */
  });

// - or -

register.clusterMetrics((err, metrics) => {
  // ...
});

Pushgateway

可以通过Pushgateway来push metrics。

注意时间戳会在metrics被push前被剥夺，因为Pushgateway >= 0.4 将不接受时间戳。

const client = require('prom-client');
let gateway = new client.Pushgateway('http://127.0.0.1:9091');

gateway.pushAdd({ jobName: 'test' }, function(err, resp, body) {}); //Add metric and overwrite old ones
gateway.push({ jobName: 'test' }, function(err, resp, body) {}); //Overwrite all metrics (use PUT)
gateway.delete({ jobName: 'test' }, function(err, resp, body) {}); //Delete all metrics for jobName

//All gateway requests can have groupings on it
gateway.pushAdd({ jobName: 'test', groupings: { key: 'value' } }, function(
  err,
  resp,
  body
) {});

//It's possible to extend the Pushgateway with request options from nodes core http/https library
gateway = new client.Pushgateway('http://127.0.0.1:9091', { timeout: 5000 }); //Set the request timeout to 5000ms

Utilites

为了方便，有两个桶生成器函数——线性和指数的。

const client = require('prom-client');
new client.Histogram({
  name: 'metric_name',
  help: 'metric_help',
  buckets: client.linearBuckets(0, 10, 20) //Create 20 buckets, starting on 0 and a width of 10
});

new client.Histogram({
  name: 'metric_name',
  help: 'metric_help',
  buckets: client.exponentialBuckets(1, 2, 5) //Create 5 buckets, starting on 1 and with a factor of 2
});

在注册器和本工程的主文件中，prometheus期待的内类类型都是作为常量输出的，称为contentType。

---

查看作者首页