prometheus_exporter 0.6.0

Helper libary to export prometheus metrics using hyper.
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87

# prometheus_exporter

[![Build Status](https://travis-ci.org/AlexanderThaller/prometheus_exporter.svg?branch=master)](https://travis-ci.org/AlexanderThaller/prometheus_exporter)
[![crates.io](https://img.shields.io/crates/v/prometheus_exporter.svg)](https://crates.io/crates/prometheus_exporter)
[![docs.rs](https://docs.rs/prometheus_exporter/badge.svg)](https://docs.rs/prometheus_exporter)

Helper libary to export prometheus metrics using hyper. It's intended to help
writing prometheus exporters without the need to setup and maintain a http
webserver. If the program also uses a http server for other purposes this
package is probably not the best way and
[rust-prometheus](https://github.com/pingcap/rust-prometheus) should be used
directly.

It uses [rust-prometheus](https://github.com/pingcap/rust-prometheus) for
collecting and rendering the prometheus metrics and
[hyper](https://github.com/hyperium/hyper) for exposing the metrics through
http.

**NOTICE:** You have to use the same prometheus crate version that is used by
this crate to make sure that the global registrar use by the prometheus macros
works as expected. This crate re-exports the prometheuse crate to make it easier
to keep versions in sync (see examples). Currently this crate uses prometheus
version `0.9`.

## Usage

Add this to your `Cargo.toml`:

```toml
[dependencies]
prometheus_exporter = "0.5"
```

There are three ways on how to use the exporter:

* `PrometheusExporter::run`: Just starts the hyper http server and exports
    metrics from the global prometheus register under the path `/metrics`.
    Allows the most freedom on how and when to update/generate metrics.

* `PrometheusExporter::run_and_notify`: Starts the http server and opens
    channels to allow notification of when a request is made. This is usefull
    for cases where metrics should be updated everytime somebody calls the
    `/metrics` path.

* `PrometheusExporter::run_and_repeat`: Starts the http server and opens
    channels that will send a message to the original caller when a duration
    inteval is reached. This will be repeated forever. This is usefull for cases
    where metrics should be gathered in a set interval. For example if the
    metric collection is expensive it makes more sense to not collect the
    metrics all the time.

For examples on how to use `prometheus_exporter` see the examples folder.

A very simple example looks like this (from `examples/simple/src/main.rs`):

```rust
// Will create an exporter with a single metric that does not change

use env_logger::{
    Builder,
    Env,
};
use prometheus_exporter::{
    PrometheusExporter,
    prometheus::register_gauge,
};
use std::net::SocketAddr;

fn main() {
    // Setup logger with default level info so we can see the messages from
    // prometheus_exporter.
    Builder::from_env(Env::default().default_filter_or("info")).init();

    // Parse address used to bind exporter to.
    let addr_raw = "0.0.0.0:9184";
    let addr: SocketAddr = addr_raw.parse().expect("can not parse listen addr");

    // Create metric
    let metric =
        register_gauge!("the_answer", "to everything").expect("can not create gauge the_answer");

    metric.set(42.0);

    // Start exporter and makes metrics available under http://0.0.0.0:9184/metrics
    PrometheusExporter::run(&addr).expect("can not run exporter");
}
```