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