reblocks-prometheus
2025-06-22
This is an addon for Reblocks Common Lisp framework which allows to gather metrics in Prometheus format.
reblocks-prometheus - This is an addon for Reblocks Common Lisp framework which allows to gather metrics in Prometheus format.
REBLOCKS-PROMETHEUS ASDF System Details
- Description: This is an addon for Reblocks Common Lisp framework which allows to gather metrics in Prometheus format.
- Licence: Unlicense
- Author: Alexander Artemenko
- Homepage: https://40ants.com/reblocks-prometheus
- Bug tracker: https://github.com/40ants/reblocks-prometheus/issues
- Source control: GIT
- Depends on: 40ants-routes, prometheus, prometheus-gc, prometheus.collectors.process, prometheus.collectors.sbcl, prometheus.formats.text, reblocks
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.