Rust Prometheus exporter base
Rust base library for Prometheus exporters
Goal
This crate is meant to make writing a proper Prometheus exporter with a minimal effort. It gives you two things.
- A Rust-y, fluent way to create Prometheus compliant outputs:
.with_name
.with_metric_type
.with_help
.build
.render_and_append_instance
.render
build
- It optionally gives you a boilerplate-free Hyper server for exposing your Prometheus metrics. It handles most mundane tasks, such as setting up an Hyper server and doing some basic checks (such as rejecting anything but
GET
and responding only to the/metrics
suffix) so all you have to do is supply a Boxed future that will handle your logic (remember to specify thehyper_server
feature flag in yourCargo.toml
as well).
I use it on these crates: prometheus_wireguard_exporter and prometheus_iota_exporter so please refer to these crates if you want to see a real-world example. More simple examples are available in the examples folder.
Usage
PrometheusMetric
The PrometheusMetric
struct is used by instantiating it and then "rendering" the header and values - optionally specifying labels. This is an example taken from the documentation:
.with_name
.with_metric_type
.with_help
.build
.render_and_append_instance
.render
build
This will give you something like this:
For a more complete example please refer to the examples folder.
Hyper server
To use Hyper server all you have to do is specify the hyper_server
feature flag and call the render_prometheus
function. This function requests you to pass:
- The address/port to listen to. For example
([0, 0, 0, 0], 32221).into()
listens on every interface on port 32221. - An arbitrary struct to be passed back to your code (useful for command line arguments). If you don't need it, pass an empty struct.
- The code your exporter is supposed to do. This takes the form of a closure returning a boxed future. The closure itself will receive the http request data along with the aforementioned struct (point 2). The output is expected to be a string.
For example:
render_prometheus.await;
As you can see, in order to keep things simple, the Hyper server does not enforce anything to the output. It's up to you to return a meaningful string by using the above mentioned structs.
Testing
Once running, test your exporter with any GET enabled tool (such as a browser) at http://127.0.0.1:<your_exporter_port>/metric
.
License
Please see the LICENSE file (spoiler alert: it's MIT).