reblocks-prometheus

2025-06-22

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

Upstream URL

github.com/40ants/reblocks-prometheus

Author

Alexander Artemenko

License

Unlicense
README

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

package reblocks-prometheus

Classes

METRICS-ROUTE

class reblocks-prometheus:metrics-route (route)

Readers

reader reblocks-prometheus:stats-registry (metrics-route) (= (reblocks-prometheus/app::make-reblocks-metrics-registry))

PROMETHEUS-APP-MIXIN

class reblocks-prometheus: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

function reblocks-prometheus:metrics-registry

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

Macros

macro reblocks-prometheus:metrics (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.


[generated by 40ANTS-DOC]

Dependencies (12)

  • 40ants-asdf-system
  • cffi
  • ci
  • doc
  • docs-builder
  • named-readtables
  • prometheus.cl
  • prometheus-gc
  • pythonic-string-reader
  • reblocks
  • routes
  • rove
  • GitHub
  • Quicklisp