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

You need to call spawn_http_server() somewhere near the start of your program. (Personally I do it straight after I initialize the log backend.) 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
foobar 20
login_attempts{result="Success",user="7"} 1
login_attempts{user="7"} 1

By default the HTTP server runs on port 9898, but you can change this by setting the RUST_METRICS_PORT environment variable. Tip: If you want to specify the metrics port in your application itself, you can do so like this:

std::env::set_var("RUST_METRICS_PORT", "1234");
epimetheus::spawn_http_server();

By the way, if you try to update a metric before calling spawn_http_server(), the update is thrown away silently, and quickly. This means that if you want to disable your metrics, you can just omit the call to spawn_http_server() and all your metric updates become fairly cheap no-ops.

if opts.enable_metrics {
    epimetheus::spawn_http_server();
}

Macros

metric

Refer to a metric.

Structs

Metric

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

Functions

existing_server_port	Get the port of a running server if it exists.
spawn_http_server