15v-pmx 中文文档教程

Question

PM2 programmatic integration

PMX 允许您使用 PM2 和 Keymetrics 创建高级交互.io。

Table of Contents

• Installation
• Expose Custom Metrics
• Expose Triggerable Runtime Functions
• Report Exceptions and Alerts
• Report Custom Events
• Monitor network traffic

Installation

使用 npm 安装 pmx：

$ npm install pmx --save

Expose Metrics: Measure anything

PMX 允许您实时和随时间将代码中的代码指标公开给 PM2 monit 命令或 Keymetrics 仪表板。

提供 4 种测量值：

• Simple metrics: Values that can be read instantly
  • eg. Monitor variable value
• Counter: Things that increment or decrement
  • eg. Downloads being processed, user connected
• Meter: Things that are measured as events / interval
  • eg. Request per minute for a http server
• Histogram: Keeps a reservoir of statistically relevant values biased towards the last 5 minutes to explore their distribution
  • eg. Monitor the mean of execution of a query into database

Metric: Simple value reporting

这允许显示可立即读取的值。

var probe = pmx.probe();

// Here the value function will be called each second to get the value
// returned by Object.keys(users).length
var metric = probe.metric({
  name    : 'Realtime user',
  value   : function() {
    return Object.keys(users).length;
  }
});

// Here we are going to call valvar.set() to set the new value
var metric_2 = probe.metric({
  name    : 'Realtime Value'
});

metric_2.set(23);

Options

• name: Probe name
• value: (optional) function that allows to monitor a global variable

Counter: Sequential value change

递增或递减的事物。

var probe = pmx.probe();

// The counter will start at 0
var counter = probe.counter({
  name : 'Current req processed'
});

http.createServer(function(req, res) {
  // Increment the counter, counter will eq 1
  counter.inc();
  req.on('end', function() {
    // Decrement the counter, counter will eq 0
    counter.dec();
  });
});

Options

• name: Probe name

Meter: Average calculated values

作为事件/间隔测量的事物。

var probe = pmx.probe();

var meter = probe.meter({
  name      : 'req/sec',
  samples   : 1  // This is per second. To get per min set this value to 60
});

http.createServer(function(req, res) {
  meter.mark();
  res.end({success:true});
});

Options

• name: Probe name
• samples: (optional)(default: 1) Rate unit. Defaults to 1 sec.
• timeframe: (optional)(default: 60) timeframe over which events will be analyzed. Defaults to 60 sec.

Histogram

保留偏向最后 5 分钟的统计相关值库，以探索它们的分布。

var probe = pmx.probe();

var histogram = probe.histogram({
  name        : 'latency',
  measurement : 'mean'
});

var latency = 0;

setInterval(function() {
  latency = Math.round(Math.random() * 100);
  histogram.update(latency);
}, 100);

Options

• name: Probe name
• agg_type : (optional)(default: none) Can be sum, max, min, avg (default) or none. It will impact the way the probe data are aggregated within the Keymetrics backend. Use none if this is irrelevant (eg: constant or string value).
• alert : (optional)(default: null) For Meter and Counter probes. Creates an alert object (see below).

Expose Functions: Trigger Functions remotely

从 Keymetrics 远程触发功能。 这些指标发生在“自定义操作”部分下的主要关键指标仪表板页面中。

Simple actions

简单的操作允许从 Keymetrics 触发一个功能。 该函数将函数作为参数（在此处回复），并且需要在作业完成后调用。

示例：

var pmx = require('pmx');

pmx.action('db:clean', function(reply) {
  clean.db(function() {
    /**
     * reply() must be called at the end of the action
     */
     reply({success : true});
  });
});

Scoped actions (beta)

Scoped Actions 是高级远程操作，也可以从 Keymetrics 触发。

两个参数被传递给函数，数据（从 Keymetrics 发送的可选数据）和允许发出日志数据并结束作用域操作的 res。

示例：

pmx.scopedAction('long running lsof', function(data, res) {
  var child = spawn('lsof', []);

  child.stdout.on('data', function(chunk) {
    chunk.toString().split('\n').forEach(function(line) {
      res.send(line); // This send log to Keymetrics to be saved (for tracking)
    });
  });

  child.stdout.on('end', function(chunk) {
    res.end('end'); // This end the scoped action
  });

  child.on('error', function(e) {
    res.error(e);  // This report an error to Keymetrics
  });

});

Alert System for Custom Metrics

（特定于关键指标）

此警报系统可以监视探测值并在达到特定值时启动异常。

cpu_usage 变量示例：

var metric = probe.metric({
  name  : 'CPU usage',
  value : function() {
    return cpu_usage;
  },
  alert : {
    mode  : 'threshold',
    value : 95,
    msg   : 'Detected over 95% CPU usage', // optional
    func  : function() { //optional
      console.error('Detected over 95% CPU usage');
    },
    cmp   : "<" // optional
  }
});

Options

• mode : threshold, threshold-avg.
• value : Value that will be used for the exception check.
• msg : String used for the exception.
• func : optional. Function declenched when exception reached.
• cmp : optional. If current Probe value is not <, >, = to Threshold value the exception is launched. Can also be a function used for exception check taking 2 arguments and returning a bool.
• interval : optional, threshold-avg mode. Sample length for monitored value (180 seconds default).
• timeout : optional, threshold-avg mode. Time after which mean comparison starts (30 000 milliseconds default).

Report Alerts: Errors / Uncaught Exceptions

（特定于 Keymetrics）

默认情况下，一旦 PM2 链接到 Keymetrics，您将收到任何未捕获异常的警报。 这些错误可在 Keymetrics 的问题 选项卡中访问。

Custom alert notification

如果您需要警告任何严重错误，您可以通过编程方式进行：

var pmx = require('pmx');

pmx.notify({ success : false });

pmx.notify('This is an error');

pmx.notify(new Error('This is an error'));

Add Verbosity to an Alert: Express Error handler

当发生未捕获的异常时，您可以跟踪它是从哪些路由中抛出的。 为此，您必须在路由安装结束时附加中间件 pmx.expressErrorHandler：

var pmx = require('pmx');

// All my routes
app.get('/' ...);
app.post(...);
// All my routes

// Here I attach the middleware to get more verbosity on exception thrown
app.use(pmx.expressErrorHandler());

Emit Events

发出事件并获取历史和统计信息。 这在 Keymetrics 的事件页面中可用。

var pmx = require('pmx');

pmx.emit('user:register', {
  user : 'Alex registered',
  email : 'thorustor@gmail.com'
});

Application level network traffic monitoring / Display used ports

您可以通过在初始化 PMX 时添加选项 network: true 来监控特定应用程序的网络使用情况。 如果您在初始化 pmx 时启用标志 ports: true，它将显示您的应用正在侦听的端口。

这些指标将显示在自定义指标部分的关键指标仪表板中。

示例：

pmx.init({
  [...]
  network : true, // Allow application level network monitoring
  ports   : true  // Display ports used by the application
});

Advanced PMX configuration

var pmx = require('pmx').init({
  network       : true, // (default: false) Network monitoring at the application level
  ports         : true, // (default: false) Shows which ports your app is listening on
  // can be 'express', 'hapi', 'http', 'restify'
  excludedHooks: []
});

License

麻省理工学院