hopr_metrics/lib.rs
1//! # HOPR Metrics Collection
2//!
3//! The purpose of the `hopr_metrics` Rust crate is to create a thin wrapper
4//! over the [Prometheus Metrics Rust API](https://docs.rs/prometheus/latest/prometheus/) or
5//! a similar metrics library, should it change in the future.
6//!
7//! This wrapper merely simplifies the 3 basic Metric Types:
8//!
9//! - Counter (integer only)
10//! - Gauge (floating point only)
11//! - Histogram (floating point only)
12//!
13//! The above three types are wrapped using the following structs:
14//!
15//! - [SimpleCounter]
16//! - [MultiCounter]
17//! - [SimpleGauge]
18//! - [MultiGauge]
19//! - [SimpleHistogram]
20//! - [MultiHistogram]
21//!
22//! The "simple" types represent a singular named metrics, whereas the "multi" metrics represent a
23//! vector extension.
24//!
25//! The vector extensions basically maintain multiple labelled metrics in a single
26//! entity. This makes it possible to have categorized metric values within a single metric, e.g.
27//! counter of successful HTTP requests categorized by HTTP method.
28//!
29//! The metrics are registered within the global metrics registry (singleton).
30//! Currently, the crate does not support additional individual registries apart from the global one.
31//!
32//! ### Usage in Rust code
33//!
34//! When writing pure Rust code that uses this crate, one can use the above structs by directly instantiating them.
35//! During their construction, the metric registers itself in the global metrics registry.
36//!
37//! #### Example use in Rust
38//!
39//! ```rust
40//! use hopr_metrics::metrics::*;
41//!
42//! let metric_counter = SimpleCounter::new("test_counter", "Some testing counter").unwrap();
43//!
44//! // Counter can be only incremented by integers only
45//! metric_counter.increment_by(10);
46//!
47//! let metric_gauge = SimpleGauge::new("test_gauge", "Some testing gauge").unwrap();
48//!
49//! // Gauges can be incremented and decrements and support floats
50//! metric_gauge.increment(5.0);
51//! metric_gauge.decrement(3.2);
52//!
53//! let metric_histogram = SimpleHistogram::new("test_histogram", "Some testing histogram", vec![1.0, 2.0]).unwrap();
54//!
55//! // Histograms can observe floating point values
56//! metric_histogram.observe(10.1);
57//!
58//! // ... and also can be used to measure time durations in seconds
59//! let timer = metric_histogram.start_measure();
60//! std::thread::sleep(std::time::Duration::from_secs(1));
61//! metric_histogram.record_measure(timer);
62//!
63//! // Multi-metrics are labeled extensions
64//! let metric_counts_per_version = MultiCounter::new("test_multi_counter", "Testing labeled counter", &["version"]).unwrap();
65//!
66//! // Tracks counters per different versions
67//! metric_counts_per_version.increment_by(&["1.0.0"], 2);
68//! metric_counts_per_version.increment_by(&["1.0.1"], 1);
69//!
70//! // All metrics live in a global state and can be serialized at any time
71//! let gathered_metrics = gather_all_metrics();
72//!
73//! // Metrics are in text format and can be exposed using an HTTP API endpoint
74//! println!("{:?}", gathered_metrics);
75//! ```
76//!
77
78/// Contains definitions of metric types.
79pub mod metrics;
80
81pub use crate::metrics::*;