Epimetheus

An easy-to-use prometheus-compatible metrics library.

Epimetheus is probably the easiest way to get your Rust application serving metrics. Just scatter your code with instrumentation; everything else is automatic.

Watch your hashmaps grow!

rust metric!(my_data_len).set(my_data.len()); metric!(my_data_cap).set(my_data.capacity());

Monitor the latency of your functions!

rust let start = Instant::now(); my_function(); metric!(my_function_duration_sum).add(start.elapsed().as_secs_f64()); metric!(my_function_duration_count).add(1.0);

Track the status codes of your responses!

rust let resp = compute_response(); metric!(responses{code=resp.status()}).add(1.0); Ok(resp)

Then connect to port 9898 to see what's happening:

$ curl localhost:9898 my_data_cap 1024 my_data_len 764 my_function_duration_count 6032 my_function_duration_sum 8.32 responses{code="200 OK"} 5443 responses{code="404 Not Found"} 587 responses{code="500 Internal Server Error"} 2

Features

• Multi-threaded OK! Everyone shares the same set of metrics.
• The format is prometheus-compatible. Point prometheus' watchful eye at your program and get nice graphs.
• Updating metrics is fast (...mostly. See below.)
• The HTTP thread is spawned the first time you update a metric.
• The port number can be customised via the RUST_METRICS_PORT environment variable.
• The code is very readable - around 100 sloc. Take a look!
• Public domain.

Performance

• Updating an unlabelled metric (like my_data_len above) is very fast. It takes around 30ns on my work machine, around 45ns on my laptop.
• Updating a labelled metric (like responses above) requires allocation and is quite slow - on my machine, it's 5x slower than modifying an unlabelled metric.
• The HTTP server is extremely dumb and can only handle one client at a time; typically this doesn't matter.

Other stuff

You may think it's a bit agro for some library to be spawning threads behind your back at unspecified times. Well, sure, it is, a bit... but we're already in the business of creating global shared resources in the name of ergonomics, so the decision to auto-spawn the HTTP thread is at least in-character.

Epimetheus is the brother of Prometheus, hence the crate's name.

Contributing

Please send bug reports to <~asayers/public-inbox@lists.sr.ht>.

Please send patches to <~asayers/public-inbox@lists.sr.ht>, and include the following text:

I dedicate any and all copyright interest in this software to the public domain. I make this dedication for the benefit of the public at large and to the detriment of my heirs and successors. I intend this dedication to be an overt act of relinquishment in perpetuity of all present and future rights to this software under copyright law.