🌡️ Koa Prometheus

A configurable Prometheus data collector with Koa middleware

Overview
|
Usage
|
Api
|
Configuration
|
Contributors

![License]()
!type
!language

Overview

This package is a thin wrapper around
prom-client &
metrics, to provide
prometheus formatted metrics for Koa applications.

It provides the following types of metric;

* 📊 Histogram - Raw number counts, bucketed
* 📈 Summary - Percentile calculated buckets
* ⏱ Meter - an EWMA decaying gauge for counting over time
* 🌡 Gauge - A counter that can go both up and down
* 🎚 Counter - Count number of times something happens
* 🏷 Labelling - Labelling to enable powerful Prometheus querying

It will also provide you with a /metrics endpoint to expose these
metrics to prometheus

---

$3

koa-prometheus is purely _config
based_
and configurable, but you can attach it to your Koa service using
default metrics with the following;

``js
import Koa from 'koa'
import Meter from '@uswitch/koa-prometheus'

const app = new Koa()
const meters = Meter({ / Config / }, { loadDefaults: true })

app.use(meters.middleware) // The middleware that makes the meters available

app.get('/metrics', async (ctx) => (ctx.body = await meters.print()))

app.on(eventAccess, (ctx) => meters.automark(ctx))
app.on(eventError, () => meters.errorRate.mark(1))

app.listen(3000, () => signal.start(Listening on port 3000))
`


N.B. See href="https://github.com/uswitch/koa-core">
koa-core

#### Purely config

The main philsophy of Koa prometheus is to provide a way to
configure the metrics, and how to collect them, in pure JSON.

To do this, you can create a config file that contains a _list_ of
metrics, _.e.g_

`json
[
// A manually invoked meter
{
"name": "namespace_metric_name",
"help": "A description of the metric",
"type": "Counter"
},
// An automark meter
{
"name": "namespace_autocollected_metric",
"help": "A description of the metric",
"type": "Histogram",
"labelNames": [
{ "key": "method", "path": ["path", "to", "method"] },
{ "key": "status", "path": ["path", "to", "status"] }
],
"mark": {
"method": "observe",
"path": [ "path","to","value" ]
}
}
]
`

See the
schema
or the
defaults
for a more detailed look at how they are configured.

$3

You get back the configured meter when you instantiate it, and you
will get

#### Manually marking a meter

If you have a manual meter it will be available on the meters
object.
If you want to add labels to the meter, you must add them **in the
order** they are defined in the config, _i.e._

`js
// "labelName": [ "a", "b", "c" ]

meter
.myMeter
.labels("value for a", "value for b", "value for c")
.inc(1)
`

#### NodeJS metrics & GC Metrics

This library also utilises prom-client's collectDefaultMetrics &
node-prometheus-gc-stats
to collect CPU & Garbage Collection stats

#### Service standard metrics

To comply with Uswitch [service standard]() monitoring, enable service standards:

`js
const meters = Meter({ / Config / }, { loadStandards: true })
`

These will overwrite the http_request_duration_seconds, http_requests_total and errors_total metrics. The first two are automarked by @uswitch/koa-access. Mark the errors_total metric manually:
`js
// Directly
app.on('error', (err, ctx) => {
meters.errorsTotal.labels(err.name).inc(1)
})
// Or with @uswitch/koa-tracer
app.on(eventError, (err, ctx) => {
meters.errorsTotal.labels(err.name).inc(1)
})
``

Contributors

Thanks goes to these wonderful people (emoji key):

|
_{Dom Charlesworth}
📖 💻 🤔 🔌 |
_{David Annez}
💻 🤔 🔌 |
| :---: | :---: |

This project follows the all-contributors specification. Contributions of any kind welcome!