[−][src]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 |
Functions
existing_server_port | Get the port of a running server if it exists. |
spawn_http_server |