Crate prometheus_exporter

Helper to export prometheus metrics via http.

Information on how to use the prometheus crate can be found at prometheus.

Basic Example

The most basic usage of this crate is to just start a http server at the given binding which will export all metrics registered on the global prometheus registry:

use prometheus_exporter::{
    self,
    prometheus::register_counter,
};

let binding = "127.0.0.1:9184".parse().unwrap();
// Will create an exporter and start the http server using the given binding.
// If the webserver can't bind to the given binding it will fail with an error.
prometheus_exporter::start(binding).unwrap();

// Create a counter using the global prometheus registry and increment it by one.
// Notice that the macro is coming from the reexported prometheus crate instead
// of the original crate. This is important as different versions of the
// prometheus crate have incompatible global registries.
let counter = register_counter!("user_exporter_counter", "help").unwrap();
counter.inc();

Wait for request

A probably more useful example in which the exporter waits until a request comes in and then updates the metrics on the fly:

use prometheus_exporter::{
    self,
    prometheus::register_counter,
};

let binding = "127.0.0.1:9185".parse().unwrap();
let exporter = prometheus_exporter::start(binding).unwrap();

let counter = register_counter!("example_exporter_counter", "help").unwrap();

// Wait will return a waitgroup so we need to bind the return value.
// The webserver will wait with responding to the request until the
// waitgroup has been dropped
let guard = exporter.wait_request();

// Updates can safely happen after the wait. This has the advantage
// that metrics are always in sync with the exporter so you won't
// get half updated metrics.
counter.inc();

// Drop the guard after metrics have been updated.
drop(guard);

Update periodically

Another use case is to update the metrics periodically instead of updating them for each request. This could be useful if the generation of the metrics is expensive and shouldn’t happen all the time.

use prometheus_exporter::{
    self,
    prometheus::register_counter,
};

let binding = "127.0.0.1:9186".parse().unwrap();
let exporter = prometheus_exporter::start(binding).unwrap();

let counter = register_counter!("example_exporter_counter", "help").unwrap();

// Wait for one second and then update the metrics. `wait_duration` will
// return a mutex guard which makes sure that the http server won't
// respond while the metrics get updated.
let guard = exporter.wait_duration(std::time::Duration::from_millis(100));
counter.inc();
drop(guard);

You can find examples under /examples.

Crate Features

logging

Enabled by default: yes

Enables startup logging and failed request logging using the log crate.

internal_metrics

Enabled by default: yes

Enables the registration of internal metrics used by the crate. Will enable the following metrics:

• prometheus_exporter_requests_total: Number of HTTP requests received.
• prometheus_exporter_response_size_bytes: The HTTP response sizes in bytes.
• prometheus_exporter_request_duration_seconds: The HTTP request latencies in seconds.

This feature will not work in combination with using a custom registry.

Re-exports

pub use prometheus;

Structs

Builder

Builder to create a new crate::Exporter.

Exporter

Helper to export prometheus metrics via http.

Enums

Error

Errors that can occur while building or running an exporter.

Functions

start

Create and start a new exporter which uses the given socket address to export the metrics.