extend unittests, simplify API, update README, use npm5 and package-lock.json, add node7 to travis config

Conflicts:
	README.md
	package.json

.travis.yml

@@ -1,5 +1,4 @@
 language: node_js
 node_js:
     - "6"
-    - "5"
-    - "4"
+    - "7"

README.md

@@ -2,29 +2,27 @@
 
 # express prometheus bundle
 
-Express middleware with popular prometheus metrics in one bundle. It's also compatible with koa v1 (see below).
+Express middleware with popular prometheus metrics in one bundle. It's also compatible with koa v1 and v2 (see below).
 
-Internally it uses **prom-client**. See: https://github.com/siimon/prom-client
+Internally it uses **prom-client**. See: https://github.com/siimon/prom-client (^9.0.0)
 
 Included metrics:
 
 * `up`: normally is just 1
 * `http_request_duration_seconds`: http latency histogram labeled with `status_code`, `method` and `path`
 
-**Please not version 2.x is NOT compatible with 1.x**
-
 ## Install
 
 ```
 npm install express-prom-bundle
 ```
 
-## Usage
+## Sample uUsage
 
 ```javascript
 const promBundle = require("express-prom-bundle");
-const metricsMiddleware = promBundle({/* options */ });
 const app = require("express")();
+const metricsMiddleware = promBundle({includeMethod: true});
 
 app.use(metricsMiddleware);
 app.use(/* your middleware */);
@@ -36,7 +34,7 @@ app.listen(3000);
 
 **ALERT!**
 
-The order in wich the routes are registered is important, since
+The order in which the routes are registered is important, since
 **only the routes registered after the express-prom-bundle will be measured**
 
 You can use this to your advantage to bypass some of the routes.
@@ -44,25 +42,58 @@ See the example below.
 
 ## Options
 
-* **buckets**: buckets used for `http_request_seconds` histogram
-* **includeMethod**: include HTTP method (GET, PUT, ...) as a label to `http_request_duration_seconds`
-* **includePath**: include URL path as a label (see below)
-* **normalizePath**: boolean or `function(req)` - path normalization for `includePath` option
-* **excludeRoutes**: array of strings or regexp specifying which routes should be skipped for `http_request_duration_seconds` metric. It uses `req.path` as subject when checking
+Which labels to include in `http_request_duration_seconds` metric:
+
+* **includeStatusCode**: HTTP status code (200, 400, 404 etc.), default: **true**
+* **includeMethod**: HTTP method (GET, PUT, ...), default: **false**
+* **includePath**: URL path (see importent details below), default: **false**
+
+Extra transformation callbacks:
+
+* **normalizePath**: `function(req)` generates path values from express `req` (see details below)
+* **formatStatusCode**: `function(res)` producing final status code from express `res` object, e.g. you can combine `200`, `201` and `204` to just `2xx`.
+
+Other options:
+
+* **buckets**: buckets used for `http_request_duration_seconds` histogram
 * **autoregister**: if `/metrics` endpoint should be registered. (Default: **true**)
-* **whitelist**, **blacklist**: array of strings or regexp specifying which metrics to include/exclude
+
+Deprecated:
+
+* **whitelist**, **blacklist**: array of strings or regexp specifying which metrics to include/exclude (there are only 2 metrics)
+* **excludeRoutes**: array of strings or regexp specifying which routes should be skipped for `http_request_duration_seconds` metric. It uses `req.originalUrl` as subject when checking. You want to use express or meddleware features instead of this option.
 
 ### More details on includePath option
 
-The goal is to have separate latency statistics by URL path, e.g. `/my-app/user/`, `/products/by-category` etc.
+Let's say you want to have  latency statistics by URL path,
+e.g. separate metrics for `/my-app/user/`, `/products/by-category` etc.
 
-Just taking `req.path` as a label value won't work as IDs are often part of the URL, like `/user/12352/profile`. So what we actually need is a path template. The module tries to figure out what parts of the path are values or IDs, and what is an actual path. The example mentioned before would be normalized to `/user/#val/profile` and that will become the value for the label.
+Just taking `req.path` as a label value won't work as IDs are often part of the URL,
+like `/user/12352/profile`. So what we actually need is a path template.
+The module tries to figure out what parts of the path are values or IDs,
+and what is an actual path. The example mentioned before would be
+normalized to `/user/#val/profile` and that will become the value for the label.
 
-You can override this magical behavior and define your own function by providing an optional callback using **normalizePath** option.
+You can override this magical behavior and define your own function by
+providing an optional callback using **normalizePath** option.
+You can also replace the default **normalizePath** function globally.
+
+```javascript
+app.use(promBundle(/* options? */));
+
+// let's reuse the existing one and just add some
+// functionality on top
+const originalNormalize = promBunle.normalizePath;
+promBunle.normalizePath = (req, opts) => {
+  const path = originalNormalize(req, opts);
+  // count all docs (no matter which file) as a single path
+  return path.match(/^\/docs/) ? '/docs/*' : path;
+};
+```
 
 For more details:
  * [url-value-parser](https://www.npmjs.com/package/url-value-parser) - magic behind automatic path normalization
- * [normalizePath.js](https://github.com/jochen-schweizer/express-prom-bundle/blob/master/src/normalizePath.js) - source code for path processing, for you
+ * [normalizePath.js](https://github.com/jochen-schweizer/express-prom-bundle/blob/master/src/normalizePath.js) - source code for path processing
 
 
 
@@ -71,23 +102,20 @@ For more details:
 setup std. metrics but exclude `up`-metric:
 
 ```javascript
-"use strict";
-
 const express = require("express");
 const app = express();
 const promBundle = require("express-prom-bundle");
 
-
 // calls to this route will not appear in metrics
 // because it's applied before promBundle
 app.get("/status", (req, res) => res.send("i am healthy"));
 
-app.use(promBundle({
-    includePath: true,
-    excludeRoutes: ["/foo"]
-}));
+// register metrics collection for all routes
+// ... except those starting with /foo
+app.use("/((?!foo))*", promBundle({includePath: true}));
 
-// this call will NOT appear in metrics, because it matches excludeRoutes
+// this call will NOT appear in metrics,
+// because express will skip the metrics middleware
 app.get("/foo", (req, res) => res.send("bar"));
 
 // calls to this route will appear in metrics
@@ -98,23 +126,55 @@ app.listen(3000);
 
 See an [advanced example on github](https://github.com/jochen-schweizer/express-prom-bundle/blob/master/advanced-example.js)
 
-## koa v1 example
+## koa v2 example
 
 ```javascript
 const promBundle = require("express-prom-bundle");
-const koa = require("koa");
+const Koa = require("koa");
 const c2k = require("koa-connect");
 const metricsMiddleware = promBundle({/* options */ });
 
-const app = koa();
+const app = new Koa();
 
 app.use(c2k(metricsMiddleware));
 app.use(/* your middleware */);
 app.listen(3000);
 ```
 
+## using with kraken.js
+
+Here is meddleware config sample, which can be used in a standard **kraken.js** application:
+
+```json
+{
+  "middleware": {
+    "expressPromBundle": {
+      "route": "/((?!status|favicon.ico|robots.txt))*",
+      "priority": 0,
+      "module": {
+        "name": "express-prom-bundle",
+        "arguments": [
+          {
+            "includeMethod": true,
+            "buckets": [0.1, 1, 5]
+          }
+        ]
+      }
+    }
+  }
+}
+```
+
 ## Changelog
 
+ * **3.0.0**
+    * upgrade dependencies, most notably **prom-client** to 9.0.0
+    * switch to koa v2 in koa unittest
+    * only node v6 or higher is supported (stop supporting node v4 and v5)
+    * switch to npm5 and use package-lock.json
+    * options added: includeStatusCode, formatStatusCode
+ * **2.1.0**
+    * deprecate **excludeRoutes**, use **req.originalUrl** instead of **req.path**
  * **2.0.0**
     * the reason for the version lift were:
       * compliance to official naming recommendation: https://prometheus.io/docs/practices/naming/

advanced-example.js

@@ -4,11 +4,6 @@ const express = require('express');
 const app = express();
 const promBundle = require('express-prom-bundle');
 
-// here we want to remove default metrics provided in prom-client
-// this must be done before initializing promBundle
-clearInterval(promBundle.promClient.defaultMetrics());
-promBundle.promClient.register.clear();
-
 const bundle = promBundle({
   blacklist: [/up/],
   buckets: [0.1, 0.4, 0.7],

package.json

@@ -1,13 +1,14 @@
 {
   "name": "express-prom-bundle",
-  "version": "2.0.0",
+  "version": "3.0.0",
   "description": "express middleware with popular prometheus metrics in one bundle",
   "main": "src/index.js",
   "keywords": [
     "prometheus",
     "metrics",
     "express",
-    "bundle"
+    "path",
+    "method"
   ],
   "scripts": {
     "test": "node_modules/jasme/run.js"
@@ -16,22 +17,25 @@
   "license": "MIT",
   "dependencies": {
     "on-finished": "^2.3.0",
-    "prom-client": "^6.3.0",
+    "prom-client": "^9.0.0",
     "url-value-parser": "^1.0.0"
   },
   "devDependencies": {
-    "coveralls": "^2.11.15",
-    "eslint": "^3.11.1",
-    "express": "^4.14.0",
+    "coveralls": "^2.13.1",
+    "eslint": "^3.19.0",
+    "express": "^4.15.3",
     "istanbul": "^0.4.5",
     "jasme": "^5.2.0",
-    "koa": "^1.2.4",
-    "koa-connect": "^1.0.0",
-    "supertest": "^2.0.1",
+    "koa": "^2.2.0",
+    "koa-connect": "^2.0.0",
+    "supertest": "^3.0.0",
     "supertest-koa-agent": "^0.3.0"
   },
   "repository": {
     "type": "git",
     "url": "https://github.com/jochen-schweizer/express-prom-bundle.git"
+  },
+  "engines": {
+    "node": ">=6.0.0"
   }
 }

spec/index.spec.js

@@ -4,7 +4,7 @@
 const express = require('express');
 const supertest = require('supertest');
 const bundle = require('../');
-const koa = require('koa');
+const Koa = require('koa');
 const c2k = require('koa-connect');
 const supertestKoa = require('supertest-koa-agent');
 const promClient = require('prom-client');
@@ -169,18 +169,103 @@ describe('index', () => {
       });
   });
 
+  it('normalizePath can be replaced gloablly', done => {
+    const app = express();
+    const original = bundle.normalizePath;
+    bundle.normalizePath = () => 'dummy';
+    const instance = bundle({
+      includePath: true,
+    });
+    app.use(instance);
+    app.use('/test', (req, res) => res.send('it worked'));
+    const agent = supertest(app);
+    agent
+      .get('/test')
+      .end(() => {
+        agent
+          .get('/metrics')
+          .end((err, res) => {
+            expect(res.status).toBe(200);
+            expect(res.text).toMatch(/"dummy"/m);
+            bundle.normalizePath = original;
+            done();
+          });
+      });
+  });
+
+  it('normalizePath can be overridden', done => {
+    const app = express();
+    const instance = bundle({
+      includePath: true,
+      normalizePath: req => req.originalUrl + '-suffixed'
+    });
+    app.use(instance);
+    app.use('/test', (req, res) => res.send('it worked'));
+    const agent = supertest(app);
+    agent
+      .get('/test')
+      .end(() => {
+        agent
+          .get('/metrics')
+          .end((err, res) => {
+            expect(res.status).toBe(200);
+            expect(res.text).toMatch(/"\/test-suffixed"/m);
+            done();
+          });
+      });
+  });
+
+  it('formatStatusCode can be overridden', done => {
+    const app = express();
+    const instance = bundle({
+      formatStatusCode: () => 555
+    });
+    app.use(instance);
+    app.use('/test', (req, res) => res.send('it worked'));
+    const agent = supertest(app);
+    agent
+      .get('/test')
+      .end(() => {
+        agent
+          .get('/metrics')
+          .end((err, res) => {
+            expect(res.status).toBe(200);
+            expect(res.text).toMatch(/555/);
+            done();
+          });
+      });
+  });
+
+  it('includeStatusCode=false removes status_code label from metrics', done => {
+    const app = express();
+    const instance = bundle({
+      includeStatusCode: false
+    });
+    app.use(instance);
+    app.use('/test', (req, res) => res.send('it worked'));
+    const agent = supertest(app);
+    agent
+      .get('/test')
+      .end(() => {
+        agent
+          .get('/metrics')
+          .end((err, res) => {
+            expect(res.status).toBe(200);
+            expect(res.text).not.toMatch(/200/);
+            done();
+          });
+      });
+  });
+
   it('Koa: metrics returns up=1', done => {
-    const app = koa();
+    const app = new Koa();
     const bundled = bundle({
       whitelist: ['up']
     });
     app.use(c2k(bundled));
 
-    app.use(function*(next) {
-      if (this.path !== 'test') {
-        return yield next;
-      }
-      this.body = 'it worked';
+    app.use(function(ctx, next) {
+      return next().then(() => ctx.body = 'it worked');
     });
 
     const agent = supertestKoa(app);

spec/normalizePath.spec.js

@@ -4,25 +4,8 @@
 const normalizePath = require('../src/normalizePath');
 
 describe('normalizePath', () => {
-  it('returns original if disabled in opts', () => {
-    expect(
-     normalizePath({originalUrl: '/a/12345'}, {normalizePath: false})
-    ).toBe('/a/12345');
-  });
-
-  it('returns run callback if configured', () => {
-    expect(
-      normalizePath(
-        {originalUrl: '/a/12345'},
-        {
-          normalizePath: req => req.originalUrl + '-ok'
-        }
-      )
-    ).toBe('/a/12345-ok');
-  });
-
   it('uses UrlValueParser by default', () => {
-    expect(normalizePath({originalUrl: '/a/12345'}))
+    expect(normalizePath({url: '/a/12345'}))
       .toBe('/a/#val');
   });
 });

spec/normalizeStatusCode.spec.js

@@ -0,0 +1,12 @@
+'use strict';
+/* eslint-env jasmine */
+
+const normalizeStatusCode = require('../src/normalizeStatusCode');
+
+describe('normalizeStatusCode', () => {
+  it('returns run callback if configured', () => {
+    expect(
+      normalizeStatusCode({status_code: 500})
+    ).toBe(500);
+  });
+});

src/index.js

@@ -1,8 +1,8 @@
 'use strict';
 const onFinished = require('on-finished');
-const url = require('url');
 const promClient = require('prom-client');
 const normalizePath = require('./normalizePath');
+const normalizeStatusCode = require('./normalizeStatusCode');
 
 function matchVsRegExps(element, regexps) {
   for (let regexp of regexps) {
@@ -39,7 +39,15 @@ function prepareMetricNames(opts, metricTemplates) {
 }
 
 function main(opts) {
-  opts = Object.assign({autoregister: true}, opts || {});
+  opts = Object.assign(
+    {
+      autoregister: true,
+      includeStatusCode: true,
+      normalizePath: main.normalizePath,
+      formatStatusCode: main.normalizeStatusCode
+    },
+    opts
+  );
   if (arguments[2] && arguments[1] && arguments[1].send) {
     arguments[1].status(500)
       .send('<h1>500 Error</h1>\n'
@@ -96,18 +104,17 @@ function main(opts) {
     metrics.up.set(1);
   }
 
-  const metricsMiddleware = function(req,res) {
+  const metricsMiddleware = function(req, res) {
     res.writeHead(200, {'Content-Type': 'text/plain'});
     res.end(promClient.register.metrics());
   };
 
   const middleware = function (req, res, next) {
-
-    const path = req.path || url.parse(req.url).pathname;
+    const path = req.originalUrl || req.url; // originalUrl gets lost in koa-connect?
     let labels;
 
-    if (opts.autoregister && path === '/metrics') {
-      return metricsMiddleware(req,res);
+    if (opts.autoregister && path.match(/^\/metrics\/?$/)) {
+      return metricsMiddleware(req, res);
     }
 
     if (opts.excludeRoutes && matchVsRegExps(path, opts.excludeRoutes)) {
@@ -115,15 +122,17 @@ function main(opts) {
     }
 
     if (metrics[httpMtricName]) {
-      labels = {'status_code': 0};
+      labels = {};
       let timer = metrics[httpMtricName].startTimer(labels);
       onFinished(res, () => {
-        labels.status_code = res.statusCode;
+        if (opts.includeStatusCode) {
+          labels.status_code = opts.formatStatusCode(res, opts);
+        }
         if (opts.includeMethod) {
           labels.method = req.method;
         }
         if (opts.includePath) {
-          labels.path = normalizePath(req, opts);
+          labels.path = opts.normalizePath(req, opts);
         }
         timer();
       });
@@ -140,4 +149,6 @@ function main(opts) {
 }
 
 main.promClient = promClient;
+main.normalizePath = normalizePath;
+main.normalizeStatusCode = normalizeStatusCode;
 module.exports = main;

src/normalizePath.js

@@ -4,24 +4,14 @@ const UrlValueParser = require('url-value-parser');
 const url = require('url');
 let urlValueParser;
 
-module.exports = function(req, opts) {
-  opts = opts || {};
-
+module.exports = function(req) {
   // originalUrl is taken, because url and path can be changed
   // by middlewares such as 'router'. Note: this function is called onFinish
   /// i.e. always in the tail of the middleware chain
-  const path = url.parse(req.originalUrl).pathname;
-
-  if (opts.normalizePath !== undefined && !opts.normalizePath) {
-    return path;
-  }
-  if (typeof opts.normalizePath === 'function') {
-    return opts.normalizePath(req, opts);
-  }
+  const path = url.parse(req.originalUrl || req.url).pathname;
 
   if (!urlValueParser) {
     urlValueParser = new UrlValueParser();
   }
   return urlValueParser.replacePathValues(path);
 };
-

src/normalizeStatusCode.js

@@ -0,0 +1,5 @@
+'use strict';
+
+module.exports = function(res) {
+  return res.status_code || res.statusCode;
+};