askhogan / pmx

Keymetrics++ driver

Driver for Keymetrics

PMX is a module that allows you to create advanced interactions with Keymetrics.

With it you can:

• Trigger remote actions / functions
• Analyze custom metrics / variables (with utilities like Histogram/Counter/Metric/Meters)
• Report errors (uncaught exceptions and custom errors)
• Emit events
• Analyze HTTP latency

Installation

Install PMX and add it to your package.json via:

$ npm install pmx --save

Then init the module to monitor HTTP, Errors and diverse metrics.

var pmx = require('pmx').init(); // By default everything is enabled and ignore_routes is empty

Or choose what to monitor.

var pmx = require('pmx').init({
  http          : true, // HTTP routes logging (default: true)
  ignore_routes : [/socket\.io/, /notFound/], // Ignore http routes with this pattern (Default: [])
  errors        : true, // Exceptions loggin (default: true)
  custom_probes : true, // Custom probes (default: true)
  network       : true, // Traffic usage monitoring (default: false)
  ports         : true  // Shows which ports your app is listening on (default: false)
});

Custom monitoring

Emit Events

Emit events and get historical and statistics:

var pmx = require('pmx');

pmx.emit('user:register', {
  user : 'Alex registered',
  email : '[e-mail]'
});

Trigger function from remote

var pmx = require('pmx');

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

Note: in case of exceptions in the function, your app will not be affected

Errors

Catch uncaught exceptions:

var pmx = require('pmx').init();

Attach more data from errors that happens in Express:

var pmx = require('pmx');

app.get('/' ...);
app.post(...);

app.use(pmx.expressErrorHandler());

Trigger custom errors:

var pmx = require('pmx');

pmx.notify({ success : false });

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

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

TCP network usage monitoring

If you enable the flag network: true when you init pmx it will show network usage datas (download and upload) in realtime.

If you enable the flag ports: true when you init pmx it will show which ports your app is listenting on.

HTTP latency analysis

Monitor routes, latency and codes. REST compliant.

pmx.http(); // You must do this BEFORE any require('http')

Ignore some routes by passing a list of regular expressions.

pmx.http({
  http          : true, // (Default: true)
  ignore_routes : [/socket\.io/, /notFound/] // Ignore http routes with this pattern (Default: [])
});

This can also be done via pmx.init()

pmx.init({
  http          : true, // (Default: true)
  ignore_routes : [/socket\.io/, /notFound/] // Ignore http routes with this pattern (Default: [])
});

This module is enabled by default if you called pmx with the init() function.

Measure

Measure critical segments of you code thanks to 4 kind of probes:

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

Common options

• name : The probe name as is will be displayed on the Keymetrics dashboard
• agg_type : This param is optionnal, it 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).

Metric

Values that can be read instantly.

var probe = pmx.probe();

var metric = probe.metric({
  name  : 'Realtime user',
  agg_type: 'max',
  value : function() {
    return Object.keys(users).length;
  }
});

Counter

Things that increment or decrement.

var probe = pmx.probe();

var counter = probe.counter({
  name : 'Downloads',
  agg_type: 'sum'
});

http.createServer(function(req, res) {
  counter.inc();
  req.on('end', function() {
    counter.dec();
  });
});

Meter

Things that are measured as events / interval.

var probe = pmx.probe();

var meter = probe.meter({
  name    : 'req/min',
  agg_type: 'avg'
  seconds : 60
});

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

Options

seconds option is the measurement rate of the meter, default is 1 seconds

Histogram

Keeps a resevoir of statistically relevant values biased towards the last 5 minutes to explore their distribution.

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

measurement option can be:

• min: The lowest observed value.
• max: The highest observed value.
• sum: The sum of all observed values.
• variance: The variance of all observed values.
• mean: The average of all observed values.
• stddev: The stddev of all observed values.
• count: The number of observed values.
• median: 50% of all values in the resevoir are at or below this value.
• p75: See median, 75% percentile.
• p95: See median, 95% percentile.
• p99: See median, 99% percentile.
• p999: See median, 99.9% percentile.

Modules

Simple app

process.env.MODULE_DEBUG = true;

var pmx  = require('pmx');

var conf = pmx.initModule();

License

MIT