clack-prometheus - Clack middleware to serve stats in Prometheus format.

CLACK-PROMETHEUS ASDF System Details

• Description: Clack middleware to serve stats in Prometheus format.
• Licence: Unlicense
• Author: Alexander Artemenko svetlyak.40wt@gmail.com
• Homepage: https://40ants.com/clack-prometheus/
• Bug tracker: https://github.com/40ants/clack-prometheus/issues
• Source control: GIT
• Depends on: lack-middleware-mount, prometheus, prometheus-gc, prometheus.collectors.process, prometheus.collectors.sbcl, prometheus.formats.text

This library provides a way to collect metrics in Prometheus. In addition to system metrics collected by prometheus.cl, it also collects metrics on SBCL's garbage collection, using prometheus-gc system.

This library is used in 40ants-openrpc system to collect stats from JSON-RPC microservices.

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 :clack-prometheus)

Usage

Here is a minimal example which creates a "hello-world" clack application and adds a /metrics route to it:

CL-USER> (defparameter *handler*
           (flet ((main-app (env)
                    (declare (ignore env))
                    '(200
                      (:content-type "text/plain")
                      ("Hello, Clack!"))))
             (clack:clackup
              (clack-prometheus:with-prometheus-stats
                #'main-app)
              :port 9090)))

When you run this code, go to another terminal tab and run curl. On / path our hello world app will respond:

$ curl -s 'http://localhost:9090/'
Hello, Clack!

and on /metrics we'll see output in Prometheus format:

$ curl -s 'http://localhost:9090/metrics'
# TYPE sbcl_read_only_bytes gauge
# HELP sbcl_read_only_bytes SBCL Read-only space usage
sbcl_read_only_bytes 0
# TYPE sbcl_static_bytes gauge
# HELP sbcl_static_bytes SBCL Static space usage
sbcl_static_bytes 1744
# TYPE sbcl_dynamic_bytes gauge
# HELP sbcl_dynamic_bytes SBCL Dynamic space usage
sbcl_dynamic_bytes{object_type="other"} 27705408
sbcl_dynamic_bytes{object_type="instance"} 24370256
...
# TYPE process_resident_memory_bytes gauge
# HELP process_resident_memory_bytes Resident memory size in bytes.
process_resident_memory_bytes 244039680
# TYPE process_cpu_seconds counter
# HELP process_cpu_seconds Process CPU seconds.
process_cpu_seconds{time="stime"} 121.2
process_cpu_seconds{time="utime"} 300.51
# TYPE process_cpu_seconds_total counter
# HELP process_cpu_seconds_total Process CPU seconds total.
process_cpu_seconds_total 421.71

API

CLACK-PROMETHEUS

package clack-prometheus

Functions

function clack-prometheus:with-prometheus-stats APP &KEY (PATH (OR (UIOP/OS:GETENV "PROMETHEUS_URI") "/metrics")) (REGISTRY NIL)

Mounts a Clack sub-application to serve stats in Prometheus format.

By default, app will respons on /metrics path but you can provide an alternative either directly as PATH argument or via PROMETHEUS_URI environment variable.

To customize metrics provided by the application, you can manually create a prometheus registry by calling to PROMETHEUS:MAKE-REGISTRY, add necessary counters, gauges, etc and then pass this registry as REGISTRY argument to the with-prometheus-stats function.

[generated by 40ANTS-DOC]