Crate epimetheus

An easy-to-use prometheus-compatible metrics library

Writing metrics

A "metric" is a named value of type f64. There is a single global set of metrics; you can update it from any thread.

use epimetheus::metric;

metric!(foobar).set(12.3);
metric!(foobar).add(0.7);

If you increment a metric which has never been set, it is considered to start from zero.

metric!(barqux).add(6.5);
// now barqux = 6.5

Labels

The base part of the name is fixed statically at at compile-time. However, a metric's name may also include "labels", which are dynamic.

let user_id = 7;
metric!(login_attempts{user=user_id}).add(1.0);

The label values can be anything which implements Display.

// enum LoginResult { Success, BadUsername, BadPassword }
// impl Display for LoginResult { ... }

let result = try_log_in(user_id, passwd);
metric!(login_attempts{user=user_id, result=result}).add(1.0);

Labels can be useful, but they come at a performance cost (see README).

Seeing your metrics

...via a function call

You can call query() to see the current value of the metrics:

let mut metrics = epimetheus::query();
assert_eq!(metrics.next(), Some(("barqux".to_string(), 6.5)));
assert_eq!(metrics.next(), Some(("epimetheus_total_flushes".to_string(), 1.)));
assert_eq!(metrics.next(), Some(("epimetheus_total_updates".to_string(), 5.)));
assert_eq!(metrics.next(), Some(("foobar".to_string(), 13.)));
assert_eq!(metrics.next(), Some(("login_attempts{result=\"Success\",user=\"7\"}".to_string(), 1.)));
assert_eq!(metrics.next(), Some(("login_attempts{user=\"7\"}".to_string(), 1.)));

Note the "epimetheus_*" lines: these are metrics exposed by epimetheus itself.

...via HTTP

If you want to view the metrics externally, you should call spawn_http_server(). This will spawn a new thread which will serve metrics over HTTP.

epimetheus::spawn_http_server();

Connect to the server to see the current values of all metrics. Metrics appear in the output after being updated for the first time.

$ curl localhost:9898
barqux 6.5
epimetheus_total_flushes 2
epimetheus_total_updates 5
foobar 13
login_attempts{result="Success",user="7"} 1
login_attempts{user="7"} 1

Macros

metric

Refer to a metric.

Structs

Metric

A named metric; it has a associated global mutable f64 value.

Functions

query	Get the current state of the metrics.
spawn_http_server	Spawn a thread which serves metrics over HTTP.