reblocks-prometheus - This is an addon for Reblocks Common Lisp framework which allows to gather metrics in Prometheus format.

REBLOCKS-PROMETHEUS ASDF System Details

This is an addon for Reblocks Common Lisp framework which allows to gather metrics in Prometheus format.

Installation

You can install this library from Quicklisp, but you want to receive updates quickly, then install it from Ultralisp.org:

(ql-dist:install-dist "http://dist.ultralisp.org/"
                      :prompt nil)
(ql:quickload :reblocks-prometheus)

Usage

Add a special metrics route into you're app's route list. Use reblocks-prometheus:metrics macro to define this route.

(defapp app
  :prefix "/"
  :routes
  ((reblocks-prometheus:metrics (\"/metrics\" :user-metrics *user-metrics*)))
)

A new route /metrics will be added to serve metrics in Prometheus format.

Adding custom metrics

To add business specific metrics, define them as global variables and then the pass to the reblocks-prometheus:metrics macro like this:

(defparameter *load-average*
  (prometheus:make-gauge :name \"test_load_average\"
                         :help \"Test load average\"
                         :registry nil))

(defparameter *num-users*
  (prometheus:make-counter :name \"test_num_users_created\"
                           :help \"Test num users created after the last metrics collection\"
                           :registry nil))

(defparameter *user-metrics*
  (list *load-average*
        *num-users*))

(defapp app
  :prefix "/"
  :routes
  ((reblocks-prometheus:metrics (\"/metrics\" :user-metrics *user-metrics*)))
)

After this, you can change this counter and gauge using methods from prometheus.cl library:

(prometheus:gauge.set *load-average* 2)

(prometheus:counter.inc *num-users* :value 1)
(prometheus:counter.inc *num-users* :value 3)

and their values will change during subsequent get queries for /metrics page.

API

REBLOCKS-PROMETHEUS

Classes

METRICS-ROUTE

Readers

reader
(= (reblocks-prometheus/app::make-reblocks-metrics-registry))
PROMETHEUS-APP-MIXIN

A mixin which gathers some stats to report in Prometheus format.

Also, this mixin adds a /metrics slot to the app.

Use stats-registry to access the registry slot.

Functions

Call this function during handler's body to update gauges before metrics will be collected.

Macros

macro
(path &key name user-metrics) &body handler-body

This macro creates a route of metrics-route class.

The body passed as HANDLER-BODY will be executed each time when metrics are collected. You can use metrics-registry function to access the prometheus metrics registry from the handler body code.