sails-hook-prometheus

Gather Prometheus metrics for your SailsJS application. Also it will opens /metrics endpoint where Prometheus can scrap all statistics.

• sails-hook-prometheus
  • Installation
• Configuration
  • Configuration in depth
    • defaultMetrics.enabled (boolean)
    • defaultMetrics.prefix (string)
    • httpMetric.enabled (boolean)
    • httpMetric.name (string)
    • httpMetric.type (string)
    • httpMetric.help (string)
    • httpMetric.buckets (array of numbers)
    • httpMetric.route.exclude (array of strings)
    • httpMetric.urlQueryString (boolean)
    • httpMetric.urlParams (boolean)
    • upMetric.enabled (boolean)
    • upMetric.name (string)
    • upMetric.help (string)
    • throughputMetric.enabled (boolean)
    • throughputMetric.name (string)
    • throughputMetric.help (string)
    • sockets.enabled (boolean)
  • Custom metrics
    • Counter metric
    • Gauge metric
  • Labels for custom metrics
    • Example for counter metric
  • Custom /metrics endpoint
• Contributors
• License

Installation

Install and save NPM dependency.

npm install --save sails-hook-prometheus

Configuration

You can override default configuration. Create a file in /config/prometheus.js with configuration values listed bellow.

Configuration in depth

All configuration values bellow are optional.

defaultMetrics.enabled (boolean)

module.exports.prometheus = {
  defaultMetrics: {
    enabled: true
  }
}

Enable/disable metric.

defaultMetrics.prefix (string)

module.exports.prometheus = {
  defaultMetrics: {
    prefix: ``
  }
}

Prefix for default collected metrics.

httpMetric.enabled (boolean)

module.exports.prometheus = {
  httpMetric: {
    enabled: true
  }
}

Enable/disable metric.

httpMetric.name (string)

module.exports.prometheus = {
  httpMetric: {
    name: `http_request_duration_seconds`
  }
}

Help text displayed as a metric title under /metrics page.

httpMetric.type (string)

module.exports.prometheus = {
  httpMetric: {
    type: `histogram`
  }
}

You can select between histogram or summary.

httpMetric.help (string)

module.exports.prometheus = {
  httpMetric: {
    help: `duration histogram of http responses labeled with: `
  }
}

Help text displayed next to the metric name.

httpMetric.buckets (array of numbers)

module.exports.prometheus = {
  httpMetric: {
    buckets: [0.003, 0.03, 0.1, 0.3, 1.5, 10]
  }
}

Buckets related to histogram metric.

httpMetric.route.exclude (array of strings)

module.exports.prometheus = {
  httpMetric: {
    exclude: [
      '\\.css$',
      '\\.js$',
      '\\.(ico|gif|jpg|jpeg|png)$',
      '\\.(eot|ttf|woff|woff2|svg)$'
    ]
  }
}

Define which routes are excluded from histogram. Every element in array has to be a regular expression.

httpMetric.urlQueryString (boolean)

module.exports.prometheus = {
  httpMetric: {
    urlQueryString: true
  }
}

Include URL query params in path label. It is true by default but please note your Prometheus server might not be ready for this amount of data (every unique URL).

httpMetric.urlParams (boolean)

module.exports.prometheus = {
  httpMetric: {
    urlParams: true
  }
}

Include URL params in path label. It is true by default but please note your Prometheus server might not be ready for this amount of data (every unique URL).

upMetric.enabled (boolean)

module.exports.prometheus = {
  upMetric: {
    enabled: true
  }
}

Enable/disable metric.

upMetric.name (string)

module.exports.prometheus = {
  upMetric: {
    name: `up`
  }
}

upMetric.help (string)

module.exports.prometheus = {
  upMetric: {
    help: '1 = up, 0 = not up'
  }
}

throughputMetric.enabled (boolean)

module.exports.prometheus = {
  throughputMetric: {
    enabled: false
  }
}

Enable/disable metric.

throughputMetric.name (string)

module.exports.prometheus = {
  throughputMetric: {
    name: `throughput`
  }
}

throughputMetric.help (string)

module.exports.prometheus = {
  throughputMetric: {
    help: 'The number of requests served'
  }
}

sockets.enabled (boolean)

module.exports.prometheus = {
  sockets: {
    enabled: false
  }
}

Log socket requests as well. Due to the fact that status code is reserved for HTTP protocol only, the result of status code is always going to be 0.

Custom metrics

You can add two kind of metrics on your own:

• counter (increase a metric)
• gauge (increase or decrease a metric)

Counter metric

let counter = sails.hooks.prometheus.counter.setup({
  name: `testcounter`,
  help: `help to the metric`
})

counter.inc() // increase a metric by default 1

 // increase a metric by 2
counter.inc({
  amount: 2
})

// increase a metric by 10
counter.inc({
  amount: 10
})

Gauge metric

let gauge = sails.hooks.prometheus.gauge.setup({
  name: `testgauged`,
  help: `help to the metric`
})

// increase a metric by default 1
gauge.inc()

// increase a metric by 10
gauge.inc({
  amount: 10
})

// decrease a metric by default 1
gauge.dec()

// decrease a metric by 2
gauge.dec({
  amount: 2
})

// set a metric to 100
gauge.set({
  amount: 100
})

Labels for custom metrics

Both count and gauge metrics comes with labels feature as well.

Example for counter metric

let counter = sails.hooks.prometheus.counter.setup({
  name: `testcounter`,
  help: `help to the metric`
  labelNames: [`counter1`, `counter2`]
})

counter.inc({
  amount: 1,
  labels: {
    counter1: `value`
  }
})

Note: Gauge metric goes the same.

Custom /metrics endpoint

You can configure your own public route by editing /config/routes.js file.

module.exports.routes = {
  'GET /api/v1/metrics': 'prometheus/metrics',
}

Contributors

This project was originally created by Daniel Rataj.

License

MIT