Epimetheus

Middleware to automatically instrument node applications for consumption by a Prometheus server.

Prometheus is an open source monitoring solution that obtains metrics from servers by querying against the /metrics endpoint upon them.

Once instrumented, Epimetheus automatically serves response duration, event loop lag and memory metrics on the /metrics endpoint ready to be consumed by Prometheus.

Epimetheus will instrument websites and webservices that use http, express, hapi and restify.

Instrumentation

Epimetheus automatically measures a number of metrics once instrumented. There are 3 categories of instrumentation measured: response duration, event loop lag and memory. See below for details on each. The following metrics are instrumented via the /metrics endpoint:

Duration Metrics

There are two metrics measuring request duration:

http_request_duration_milliseconds (summary): a summary metric measuring the duration in milliseconds of all requests. It can be used to calculate average request durations.
http_request_buckets_milliseconds (histogram): a histogram metric used to count duration in buckets of sizes 500ms and 2000ms. This can be used to calculate apdex using a response time threshold of 500ms.

In each case, the following labels are used:

status: the http status code of the response, e.g. 200, 500
method: the http method of the request, e.g. put, post.
path: the path of the request. Note that /users/freddie is labelled /users/ so as not to flood prometheus with labels
cardinality: the cardinality of the request, e.g. /users/freddie has cardinality 'one', /users/ has cardinality 'many'

Event Loop Lag Metrics

The node event loop lag can be an strong indication of performance issues caused by node event loop blocking. The following metric can be used to monitor event loop lag:

node_lag_duration_milliseconds: a Gauge measuring the event loop lag in milliseconds. This is the difference in milliseconds between a specified duration in a call to setTimeout and the actual duration experienced.

Memory Metrics

There are three metrics that are measuring the memory usage of the node process, obtained from a call to process.memoryUsage:

node_memory_rss_bytes: a Gauge measuring the resident set size in bytes.
node_memory_heap_total_bytes: a Gauge measuring the total heap in bytes.
node_memory_heap_used_bytes: a Gauge measuring the total heap used in bytes.

Installation

> npm install --save epimetheus

Epimetheus has only one method, instrument, and it has the following signature:

instrument(server, options)

The first argument represents the server of the middleware.

The second argument is optional, and allows some configuration of epimetheus

url - the url on which to serve metrics. Defaults to /metrics.

See the following examples of use with http, express, hapi and restify.

http

const http = require('http');
const epimetheus = require('../../index');

const server = http.createServer((req, res) => {
  if(req.url !== '/metrics') {
    res.statusCode = 200;
    res.end();
  }
});

epimetheus.instrument(server);

server.listen(8003, '127.0.0.1', () => {
  console.log('http listening on 8003'); 
});

Express

const express = require('express');
const epimetheus = require('epimetheus');

const app = express();
epimetheus.instrument(app);
    
app.get('/', (req, res) => {
  res.send();
});

app.listen(3000, () => {
  console.log('express server listening on port 3000');
});

Hapi

const Hapi = require('hapi');
const epimetheus = require('epimetheus');

const server = new Hapi.Server();

server.connection({
  port: 3000
});
    
epimetheus.instrument(this.server);
    
server.route({
  method: 'GET',
  path: '/',
  handler: (req, resp) => {
    resp();
  }
});
   
server.start(() => {
  console.log('hapi server listening on port 3000');
});

Restify

const restify = require('restify');
const epimetheus = require('epimetheus');

const server = restify.createServer();

epimetheus.instrument(this.server);

server.get('/', (req, res, done) => {
  res.send();
  done();
});

server.listen(3000, () => {
  console.log('restify server listening on port 3000');
});

Try It Out

The docker-compose.yml file in the examples directory will create a prometheus server and an example each of an http, express, hapi and restify server.

Assuming you have installed docker and docker-compose, you can try it out by doing the following:

> cd examples
> docker-compose up

You can then view the prometheus server on http://127.0.0.1:9090

Etymology

Epimetheus was one of the Titans and the brother of Prometheus His name is derived from the Greek word meaning 'afterthought', which is the antonym of his brother's name, Prometheus, meaning 'forethought'.

JohnieLee / node-epimetheus