bump 6.3.3

fix: handle errors from prom-client

.eslintrc

@@ -17,6 +17,7 @@
   "extends": "eslint:recommended",
 
   "rules": {
+    "indent": [1, 2],
     "array-bracket-spacing": [2, "never"],
     "block-scoped-var": 2,
     "brace-style": [2, "1tbs"],

.npmignore

@@ -1,8 +0,0 @@
-advanced-example.js
-docker-compose.yml
-spec
-.travis.yml
-.eslintrc
-coverage
-.vscode
-Makefile

.travis.yml

@@ -1,9 +1,13 @@
 language: node_js
 node_js:
-    - "6"
-    - "8"
     - "10"
+    - "12"
+    - "14"
 notifications:
     email: false
 before_install:
     - npm install prom-client
+script:
+    - npm run lint
+    - npm test
+    - npm run dtslint-next

Makefile

@@ -1,9 +1,10 @@
 .PHONY: coverage
 
 test:
-	./node_modules/jasme/run.js
+	npm test
 lint:
 	node_modules/eslint/bin/eslint.js src
+	node_modules/.bin/dtslint types
 coverage:
 	node_modules/istanbul/lib/cli.js cover \
 		-i 'src/*' \

README.md

@@ -46,13 +46,29 @@ 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**
+* **includePath**: URL path (see important details below), default: **false**
 * **customLabels**: an object containing extra labels, e.g. ```{project_name: 'hello_world'}```.
   Most useful together with **transformLabels** callback, otherwise it's better to use native Prometheus relabeling.
 * **includeUp**: include an auxiliary "up"-metric which always returns 1, default: **true**
 * **metricsPath**: replace the `/metrics` route with a **regex** or exact **string**. Note: it is highly recommended to just stick to the default
+* **metricType**: histogram/summary selection. See more details below
+* **bypass**: function taking express request as an argument and determines whether the given request should be excluded in the metrics, default: **() => false**
 
-Extra transformation callbacks:
+### metricType option ###
+
+Two metric types are supported for `http_request_duration_seconds` metric:
+* [histogram](https://prometheus.io/docs/concepts/metric_types/#histogram) (default)
+* [summary](https://prometheus.io/docs/concepts/metric_types/#summary)
+
+Additional options for **histogram**:
+* **buckets**: buckets used for the `http_request_duration_seconds` histogram
+
+Additional options for **summary**:
+* **percentiles**: percentiles used for `http_request_duration_seconds` summary
+* **ageBuckets**: ageBuckets configures how many buckets we have in our sliding window for the summary
+* **maxAgeSeconds**: the maxAgeSeconds will tell how old a bucket can be before it is reset
+
+### Transformation callbacks ###
 
 * **normalizePath**: `function(req)`  or `Array`
   * if function is provided, then it should generate path value from express `req`
@@ -64,18 +80,13 @@ Extra transformation callbacks:
 * **formatStatusCode**: `function(res)` producing final status code from express `res` object, e.g. you can combine `200`, `201` and `204` to just `2xx`.
 * **transformLabels**: `function(labels, req, res)` transforms the **labels** object, e.g. setting dynamic values to **customLabels**
 
-Metric type:
+### Other options ###
 
-* **metricType**: two metric types are supported for `http_request_duration_seconds` metric: [histogram](https://prometheus.io/docs/concepts/metric_types/#histogram) and [summary](https://prometheus.io/docs/concepts/metric_types/#summary),  default: **histogram**
-
-Other options:
-
-* **buckets**: buckets used for `http_request_duration_seconds` histogram
-* **percentiles**: percentiles used for `http_request_duration_seconds` summary
 * **autoregister**: if `/metrics` endpoint should be registered. (Default: **true**)
 * **promClient**: options for promClient startup, e.g. **collectDefaultMetrics**. This option was added
   to keep `express-prom-bundle` runnable using confit (e.g. with kraken.js) without writing any JS code,
   see [advanced example](https://github.com/jochen-schweizer/express-prom-bundle/blob/master/advanced-example.js)
+* **promRegistry**: Optional `promClient.Registry` instance to attach metrics to. Defaults to global `promClient.register`.
 
 ### More details on includePath option
 
@@ -234,7 +245,6 @@ while replacing all HEX values starting from 5 characters and all IP addresses i
             "buckets": [0.1, 1, 5],
             "promClient": {
               "collectDefaultMetrics": {
-                "timeout": 2000
               }
             },
             "urlValueParser": {

advanced-example.js

@@ -14,7 +14,6 @@ const bundle = promBundle({
   metricsPath: '/prometheus',
   promClient: {
     collectDefaultMetrics: {
-      timeout: 1000
     }
   },
   urlValueParser: {

package.json

@@ -1,6 +1,6 @@
 {
   "name": "express-prom-bundle",
-  "version": "5.0.2",
+  "version": "6.3.3",
   "description": "express middleware with popular prometheus metrics in one bundle",
   "main": "src/index.js",
   "keywords": [
@@ -10,9 +10,17 @@
     "path",
     "method"
   ],
+  "files": [
+    "src",
+    "types/index.d.ts"
+  ],
+  "types": "types",
   "scripts": {
-    "test": "node_modules/jasme/run.js",
-    "coverage": "make coverage"
+    "test": "NODE_ENV=test node_modules/jasme/run.js",
+    "lint": "eslint src",
+    "coverage": "make coverage",
+    "dtslint": "dtslint types",
+    "dtslint-next": "dtslint --onlyTestTsNext types"
   },
   "author": "Konstantin Pogorelov <or@pluseq.com>",
   "license": "MIT",
@@ -21,24 +29,28 @@
     "url-value-parser": "^2.0.0"
   },
   "devDependencies": {
+    "@types/express": "^4.16.1",
     "coveralls": "^3.0.2",
+    "dtslint": "^0.7.1",
     "eslint": "^5.11.0",
     "express": "^4.16.4",
     "istanbul": "^0.4.5",
     "jasme": "^6.0.0",
     "koa": "^2.6.2",
     "koa-connect": "^2.0.1",
+    "prom-client": "^13.0.0",
     "supertest": "^3.3.0",
-    "supertest-koa-agent": "^0.3.0"
+    "supertest-koa-agent": "^0.3.0",
+    "typescript": "^3.4.5"
   },
   "peerDependencies": {
-    "prom-client": "^11.1.2"
+    "prom-client": ">=12.0.0"
   },
   "repository": {
     "type": "git",
     "url": "https://github.com/jochen-schweizer/express-prom-bundle.git"
   },
   "engines": {
-    "node": ">=6.0.0"
+    "node": ">=10"
   }
 }

spec/index.spec.js

@@ -200,6 +200,46 @@ describe('index', () => {
       });
   });
 
+  it('bypass requests', done => {
+    const app = express();
+    const instance = bundle({
+      bypass: (req)=> {
+        // metrics added here to attempt skipping /metrics
+        // this should fail though, because serving /metrics preceeds bypassing
+        return !!req.url.match(/test|bad.word|metrics/)
+      }
+    });
+    app.use(instance);
+    app.use('/test', (req, res) => res.send('it worked'));
+    app.use('/some/bad-word', (req, res) => res.send('it worked too'));
+    app.use('/good-word', (req, res) => res.send('this will be counted'));
+    const agent = supertest(app);
+    agent
+      .get('/test')
+      .end(() => {
+        agent
+          .get('/some/bad-word')
+          .end(() => {
+            agent
+              .get('/good-word')
+              .end(() => {
+                const metricHashMap = instance.metrics.http_request_duration_seconds.hashMap;
+                expect(metricHashMap['status_code:200']).toBeDefined();
+
+                // only /good-word should be counted
+                expect(metricHashMap['status_code:200'].count).toBe(1);
+
+                agent
+                  .get('/metrics')
+                  .end((err, res) => {
+                    expect(res.status).toBe(200);
+                    done();
+                  });
+              });
+          });
+      });
+  });
+
   it('complains about deprecated options', () => {
     expect(() => bundle({prefix: 'hello'})).toThrow();
   });
@@ -369,6 +409,27 @@ describe('index', () => {
       });
   });
 
+  it('handles errors in collectors', done => {
+    const app = express();
+    const instance = bundle({});
+    app.use(instance);
+
+    new promClient.Gauge({
+      name: 'kaboom',
+      help: 'this metric explodes',
+      collect() {
+        throw new Error('kaboom!');
+      }
+    });
+
+    // the error will NOT be displayed if NODE_ENV=test (as defined in package.json)
+
+    supertest(app)
+      .get('/metrics')
+      .expect(500)
+      .end((err) => done(err));
+  });
+
   it('customLabels={foo: "bar"} adds foo="bar" label to metrics', done => {
     const app = express();
     const instance = bundle({
@@ -443,11 +504,10 @@ describe('index', () => {
     bundle({
       promClient: {
         collectDefaultMetrics: {
-          timeout: 3000
         }
       }
     });
-    expect(spy).toHaveBeenCalledWith({timeout: 3000});
+    expect(spy).toHaveBeenCalledWith({});
   });
 
   describe('usage of clusterMetrics()', () => {
@@ -472,7 +532,10 @@ describe('index', () => {
       const agent = supertest(app);
 
       // create a fake worker, which would not respond in time
-      cluster.workers = [{send: () => {}}];
+      cluster.workers = [{
+        isConnected: () => true,
+        send: () => {}
+      }];
 
       const errorSpy = spyOn(console, 'error'); // mute console.error
 

src/index.js

@@ -17,20 +17,37 @@ function matchVsRegExps(element, regexps) {
 }
 
 function clusterMetrics() {
-    const aggregatorRegistry = new promClient.AggregatorRegistry();
+  const aggregatorRegistry = new promClient.AggregatorRegistry();
 
-    const metricsMiddleware = function(req, res) {
-      aggregatorRegistry.clusterMetrics((err, clusterMetrics) => {
-        if (err) {
-            console.error(err);
-            return res.sendStatus(500);
-        }
-        res.set('Content-Type', aggregatorRegistry.contentType);
-        res.send(clusterMetrics);
-      });
-    };
+  const metricsMiddleware = function(req, res) {
+    function sendClusterMetrics(clusterMetrics) {
+      res.set('Content-Type', aggregatorRegistry.contentType);
+      res.send(clusterMetrics);
+    }
 
-    return metricsMiddleware;
+    function sendClusterMetricsError(err) {
+      console.error(err);
+      return res.sendStatus(500);
+    }
+
+    // since prom-client@13 clusterMetrics() method doesn't take cb param,
+    // but we provide it anyway, as at this stage it's unknown which version of prom-client is used
+    const response = aggregatorRegistry.clusterMetrics((err, clusterMetrics) => {
+      if (err) {
+        return sendClusterMetricsError(err);
+      }
+      sendClusterMetrics(clusterMetrics);
+    });
+
+    // if we find out that it was a promise and our cb was useless...
+    if (response && response.then) {
+      response
+        .then(result => sendClusterMetrics(result))
+        .catch(err => sendClusterMetricsError(err));
+    }
+  };
+
+  return metricsMiddleware;
 }
 
 function main(opts) {
@@ -50,7 +67,8 @@ function main(opts) {
       normalizePath: main.normalizePath,
       formatStatusCode: main.normalizeStatusCode,
       metricType: 'histogram',
-      promClient: {}
+      promClient: {},
+      promRegistry: promClient.register
     }, opts
   );
 
@@ -90,14 +108,18 @@ function main(opts) {
         name: httpMetricName,
         help: 'duration summary of http responses labeled with: ' + labels.join(', '),
         labelNames: labels,
-        percentiles: opts.percentiles || [0.5, 0.75, 0.95, 0.98, 0.99, 0.999]
+        percentiles: opts.percentiles || [0.5, 0.75, 0.95, 0.98, 0.99, 0.999],
+        maxAgeSeconds:  opts.maxAgeSeconds,
+        ageBuckets: opts.ageBuckets,
+        registers: [opts.promRegistry]
       });
     } else if (opts.metricType === 'histogram' || !opts.metricType) {
       return new promClient.Histogram({
         name: httpMetricName,
         help: 'duration histogram of http responses labeled with: ' + labels.join(', '),
         labelNames: labels,
-        buckets: opts.buckets || [0.003, 0.03, 0.1, 0.3, 1.5, 10]
+        buckets: opts.buckets || [0.003, 0.03, 0.1, 0.3, 1.5, 10],
+        registers: [opts.promRegistry]
       });
     } else {
       throw new Error('metricType option must be histogram or summary');
@@ -111,14 +133,28 @@ function main(opts) {
   if (opts.includeUp !== false) {
     metrics.up = new promClient.Gauge({
       name: 'up',
-      help: '1 = up, 0 = not up'
+      help: '1 = up, 0 = not up',
+      registers: [opts.promRegistry]
     });
     metrics.up.set(1);
   }
 
-  const metricsMiddleware = function(req, res) {
-    res.writeHead(200, {'Content-Type': 'text/plain'});
-    res.end(promClient.register.metrics());
+  const metricsMiddleware = function(req, res, next) {
+    const sendSuccesss = (output) => {
+      res.writeHead(200, {'Content-Type': 'text/plain'});
+      res.end(output);
+    };
+
+    const metricsResponse = opts.promRegistry.metrics();
+    // starting from prom-client@13 .metrics() returns a Promise
+    if (metricsResponse.then) {
+      metricsResponse
+        .then(output => sendSuccesss(output))
+        .catch(err => next(err));
+    } else {
+      // compatibility fallback for previous versions of prom-client@<=12
+      sendSuccesss(metricsResponse);
+    }
   };
 
   const metricsMatch = opts.metricsPath instanceof RegExp ? opts.metricsPath
@@ -128,7 +164,13 @@ function main(opts) {
     const path = req.originalUrl || req.url; // originalUrl gets lost in koa-connect?
 
     if (opts.autoregister && path.match(metricsMatch)) {
-        return metricsMiddleware(req, res);
+      return metricsMiddleware(req, res, next);
+    }
+
+    // bypass() is checked only after /metrics was processed
+    // if you wish to disable /metrics use autoregister:false instead
+    if (opts.bypass && opts.bypass(req)) {
+      return next();
     }
 
     if (opts.excludeRoutes && matchVsRegExps(path, opts.excludeRoutes)) {

types/index.d.ts

@@ -0,0 +1,66 @@
+// TypeScript Version: 2.8
+
+import { Request, RequestHandler, Response } from 'express';
+import { DefaultMetricsCollectorConfiguration, Registry } from 'prom-client';
+
+export {};
+
+export = express_prom_bundle;
+
+declare namespace express_prom_bundle {
+  interface Labels {
+    [key: string]: string | number;
+  }
+
+  type NormalizePathEntry = [string | RegExp, string];
+  type NormalizePathFn = (req: Request, opts: Opts) => string;
+  type NormalizeStatusCodeFn = (res: Response) => number | string;
+  type TransformLabelsFn = (labels: Labels, req: Request, res: Response) => void;
+
+  interface Opts {
+    autoregister?: boolean;
+    buckets?: number[];
+
+    customLabels?: { [key: string]: any };
+
+    includeStatusCode?: boolean;
+    includeMethod?: boolean;
+    includePath?: boolean;
+    includeUp?: boolean;
+
+    bypass?: (req: Request) => boolean;
+
+    metricType?: 'summary' | 'histogram';
+    metricsPath?: string;
+    httpDurationMetricName?: string;
+    promClient?: { collectDefaultMetrics?: DefaultMetricsCollectorConfiguration };
+    promRegistry?: Registry;
+    normalizePath?: NormalizePathEntry[] | NormalizePathFn;
+    formatStatusCode?: NormalizeStatusCodeFn;
+    transformLabels?: TransformLabelsFn;
+
+    // https://github.com/disjunction/url-value-parser#options
+    urlValueParser?: {
+      minHexLength?: number;
+      minBase64Length?: number;
+      replaceMasks?: string[];
+      extraMasks?: string[];
+    };
+  }
+
+  interface Middleware extends RequestHandler {
+    metricsMiddleware: RequestHandler;
+  }
+
+  const normalizePath: NormalizePathFn;
+  const normalizeStatusCode: NormalizeStatusCodeFn;
+
+  function clusterMetrics(): RequestHandler;
+}
+
+interface express_prom_bundle {
+  normalizePath: express_prom_bundle.NormalizePathFn;
+  normalizeStatusCode: express_prom_bundle.NormalizeStatusCodeFn;
+}
+
+declare function express_prom_bundle(opts: express_prom_bundle.Opts): express_prom_bundle.Middleware;

types/test.ts

@@ -0,0 +1,79 @@
+import { Request, RequestHandler, Response } from 'express';
+import * as promClient from 'prom-client';
+
+import * as promBundle from 'express-prom-bundle';
+
+// $ExpectType Middleware
+const middleware: RequestHandler = promBundle({ includeMethod: true });
+
+// $ExpectType: string
+middleware.name;
+
+promClient.register.clear();
+
+// $ExpectType Middleware
+promBundle({
+  normalizePath: [
+    // collect paths like "/customer/johnbobson" as just one "/custom/#name"
+    ['^/customer/.*', '/customer/#name'],
+
+    // collect paths like "/bobjohnson/order-list" as just one "/#name/order-list"
+    ['^.*/order-list', '/#name/order-list']
+  ],
+  urlValueParser: {
+    minHexLength: 5,
+    extraMasks: [
+      'ORD[0-9]{5,}' // replace strings like ORD1243423, ORD673562 as #val
+    ]
+  }
+});
+
+promClient.register.clear();
+
+// $ExpectType Middleware
+promBundle({
+  buckets: [0.1, 0.4, 0.7],
+  includeMethod: true,
+  includePath: true,
+  customLabels: { year: null },
+  transformLabels: (labels: promBundle.Labels) => ({
+    ...labels,
+    year: new Date().getFullYear()
+  }),
+  metricType: 'summary',
+  metricsPath: '/prometheus',
+  promClient: {
+    collectDefaultMetrics: {
+    }
+  },
+  promRegistry: new promClient.Registry(),
+  urlValueParser: {
+    minHexLength: 5,
+    extraMasks: [
+      '^[0-9]+\\.[0-9]+\\.[0-9]+$' // replace dot-separated dates with #val
+    ]
+  },
+  normalizePath: [
+    ['^/foo', '/example'] // replace /foo with /example
+  ],
+  formatStatusCode: (res: Response) => res.statusCode + 100
+});
+
+// TypeScript workaround to write a readonly field
+type Writable<T> = { -readonly [K in keyof T]: T[K] };
+const wPromBundle: Writable<promBundle> = promBundle;
+
+wPromBundle.normalizePath = (req: Request, opts: promBundle.Opts) => {
+  const path = promBundle.normalizePath(req, opts);
+
+  // count all docs as one path, but /docs/login as a separate one
+  return path.match(/^\/docs/) && !path.match(/^\/login/) ? '/docs/*' : path;
+};
+
+wPromBundle.normalizeStatusCode = (res: Response) => res.statusCode.toString();
+
+// $ExpectType RequestHandler
+promBundle.clusterMetrics();
+
+// Missing test
+// const stringReturn: string = promBundle.normalizePath({}, {});

types/tsconfig.json

@@ -0,0 +1,14 @@
+{
+  "compilerOptions": {
+    "module": "commonjs",
+    "lib": ["es6"],
+    "noImplicitAny": true,
+    "noImplicitThis": true,
+    "strictNullChecks": true,
+    "strictFunctionTypes": true,
+    "baseUrl": ".",
+    "paths": { "express-prom-bundle": ["."] },
+    "noEmit": true,
+    "forceConsistentCasingInFileNames": true
+  }
+}

types/tslint.json

@@ -0,0 +1,3 @@
+{
+  "extends": "dtslint/dtslint.json"
+}