http-metrics-middleware

    2.1.2 • Public • Published

    Build Status Test Coverage npm downloads

    http-metrics-middleware

    Express middleware with useful prometheus metrics.

    This wraps prom-client, and adds some default metrics.

    Note: As of v1.2.0, this module requires Node.js v10 or above.

    Contributing

    Contributions are welcome and encouraged! Please follow the instructions in CONTRIBUTING.md.

    Usage

    Simplest usage is:

    const MetricsMiddleware = require('http-metrics-middleware')
    const express = require('express')
    
    var metrics = new MetricsMiddleware()
    app.use(metrics.initRoutes())

    With koa using koa-connect:

    const MetricsMiddleware = require('http-metrics-middleware')
    const c2k = require('koa-connect')
    
    var metrics = new MetricsMiddleware()
    app.use(c2k(metrics.initRoutes()))

    Options

    The middleware can be configured by providing an options object to the constructor.

    option default info
    metricsPath /metrics the metrics exposed path
    timeBuckets [ 0.01, 0.1, 0.5, 1, 5 ] the buckets to assign to duration histogram (in seconds)
    quantileBuckets [ 0.1, 0.5, 0.95, 0.99 ] the quantiles to assign to duration summary (0.0 - 1.0)
    quantileMaxAge 600 configures sliding time window for summary (in seconds)
    quantileAgeBuckets 5 configures number of sliding time window buckets for summary
    includeError false whether or not to include presence of an unhandled error as a label
    includePath true whether or not to include normalized URL path as a metric label - see about includePath below
    normalizePath a function(req) - generates path values from the express req object
    paramIgnores [] array of path parameters not to replace. Use with caution as this may cause high label cardinality.
    formatStatusCode (res) => res.status_code || res.statusCode a function(res) - generates path values from the express res object
    enableDurationHistogram true whether to enable the request duration histogram
    enableDurationSummary true whether to enable the request duration summary
    durationHistogramName http_request_duration_seconds the name of the duration histogram metric - must be unique
    durationSummaryName http_request_duration_quantile_seconds the name of duration summary metric - must be unique

    about includePath

    While it can be useful to know which endpoints are being exercised, including the path label can cause an explosion in tracked metrics from your service when the malicious or poorly-configured clients send strange URLs.

    For this reason, it is recommended that you set includePath to false, unless your route parameters are restricted to include only desired values.

    Paths are never included on requests which were not handled by a route with an explicit path (i.e. app.use where the first argument is a callback).

    For example:

    // here, the path label will be tracked if `includePath` is enabled
    // BUT don't do this - restrict the param with a regex like the next example
    app.get('/api/v1/:resource/*', (req, res) => {
      res.send('foo')
    })
    
    // this is better, as the resource param only matches a certain pattern
    app.get('/api/v1/:resource([a-z]+)/*', (req, res) => {
      res.send('foo')
    })
    
    // here, the path label will never be tracked 
    app.use((req, res) => {
      res.send('foo')
    })

    Defining custom metrics

    The underlying prom-client module is available for specifying your own custom metrics:

    const promClient = require('http-metrics-middleware').promClient
    
    var myHistogram = new promClient.Histogram({
      name: 'foo_duration_seconds',
      help: 'track the duration of foo',
      labelNames: [ 'bar', 'baz' ],
      buckets: [1, 2, 3, 4, 5]
    })

    Metrics

    In additional to the default metrics provided by prom-client, this module adds:

    • http_request_duration_seconds - (optional, enabled by default) http latency histogram labeled with status_code, method, path, and error (disabled by default - enable with includeError option)
      • use the enableDurationHistogram boolean property to control whether or not this is enabled
      • use the durationHistogramName property to give this metric a different name (required if you want both the histogram and summary)
    • http_request_duration_seconds - (optional, disabled by default) http latency summary labeled with status_code, method, path, and error (disabled by default - enable with includeError option)
      • use the enableDurationSummary boolean property to control whether or not this is enabled
      • use the durationSummaryName property to give this metric a different name (required if you want both the histogram and summary)
    • *_build_info - build information about the service (initialized with initBuildInfo function)
      const MetricsMiddleware = require('http-metrics-middleware')
      var metrics = new MetricsMiddleware()
      
      var ns = 'myservice'
      var version = '1.2.3'
      var revision = 'abcd1234'
      var buildTime = '2017-07-07T07:07:07.007Z'
      metrics.initBuildInfo(ns, version, revision, buildTime)

    Sample output

    http_request_duration_seconds_bucket{le="0.05",status_code="200",path="/",method="GET"} 5
    http_request_duration_seconds_bucket{le="0.1",status_code="200",path="/",method="GET"} 7
    http_request_duration_seconds_bucket{le="0.5",status_code="200",path="/",method="GET"} 10
    http_request_duration_seconds_bucket{le="1",status_code="200",path="/",method="GET"} 13
    http_request_duration_seconds_bucket{le="+Inf",status_code="200",path="/",method="GET"} 15
    http_request_duration_seconds_count{status_code="200",path="/",method="GET"} 15
    http_request_duration_seconds_sum{status_code="200",path="/",method="GET"} 18.534
    

    Install

    npm i http-metrics-middleware

    DownloadsWeekly Downloads

    680

    Version

    2.1.2

    License

    MIT

    Unpacked Size

    18.5 kB

    Total Files

    9

    Last publish

    Collaborators

    • veinfors
    • peol
    • axelsson.hakan
    • wennmo
    • qlikossbuild
    • chrismanley
    • nilzona
    • masaruhoshi
    • dhenderson