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

Set the RUST_METRICS_PORT environment variable when starting your program. An HTTP server will be spawned the first time a metric is written. Clients are sent the current state of all metrics in the Prometheus exposistion format.

$ RUST_METRICS_PORT=9898 cargo run &
$ 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

…via systemd-report

Set the RUST_METRICS_PATH environment variable when starting your program. A varlink server will be spawned the first time a metric is written. The server speaks the io.systemd.Metrics varlink protocol.

$ RUST_METRICS_PATH=/run/systemd/report/com.example.my_app cargo run &
$ systemd-report metrics
FAMILY                                          OBJECT FIELDS                         VALUE
com.example.my_app.barqux                       -      -                              6.5
com.example.my_app.epimetheus_total_flushes     -      -                              12
com.example.my_app.epimetheus_total_updates     -      -                              286571
com.example.my_app.foobar                       -      -                              1.0725e+03
com.example.my_app.login_attempts               -      {"user":"7"}                   715
com.example.my_app.login_attempts               -      {"result":"failed","user":"1"} 355000

Note: if you want systemd-report to pick up the metrics automatically, you need to choose a path in /run/systemd/report/ (if you’re root) or /run/user/$UID/systemd/report/ (otherwise).

Tip: If you’re running in via systemd, you can put something like this in the service file, and the metrics will be namespaced by the name of the unit:

Environment=RUST_METRICS_PATH=/run/systemd/report/com.example.%N

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.