Crate hopr_metrics

Expand description

§HOPR Metrics Collection

The purpose of the hopr_metrics Rust crate is to create a thin wrapper over the OpenTelemetry Metrics API.

This wrapper simplifies the 3 basic Metric Types:

Counter (integer only)
Gauge (floating point only)
Histogram (floating point only)

The above three types are wrapped using the following structs:

The “simple” types represent a singular named metrics, whereas the “multi” metrics represent a vector extension.

The vector extensions basically maintain multiple labelled metrics in a single entity. This makes it possible to have categorized metric values within a single metric, e.g. counter of successful HTTP requests categorized by HTTP method.

The metrics are registered within the global metrics provider.

§Usage in Rust code

When writing pure Rust code that uses this crate, one can use the above structs by directly instantiating them. During their construction, the metric registers itself in the global metrics provider.

§Example use in Rust

use hopr_metrics::*;

let metric_counter = SimpleCounter::new("test_counter", "Some testing counter").unwrap();

// Counter can be only incremented by integers only
metric_counter.increment_by(10);

let metric_gauge = SimpleGauge::new("test_gauge", "Some testing gauge").unwrap();

// Gauges can be incremented and decrements and support floats
metric_gauge.increment(5.0);
metric_gauge.decrement(3.2);

let metric_histogram = SimpleHistogram::new("test_histogram", "Some testing histogram", vec![1.0, 2.0]).unwrap();

// Histograms can observe floating point values
metric_histogram.observe(10.1);

// ... and also can be used to measure time durations in seconds
let timer = metric_histogram.start_measure();
std::thread::sleep(std::time::Duration::from_secs(1));
metric_histogram.record_measure(timer);

// Multi-metrics are labeled extensions
let metric_counts_per_version =
    MultiCounter::new("test_multi_counter", "Testing labeled counter", &["version"]).unwrap();

// Tracks counters per different versions
metric_counts_per_version.increment_by(&["1.0.0"], 2);
metric_counts_per_version.increment_by(&["1.0.1"], 1);

// All metrics live in a global state and can be serialized at any time
let gathered_metrics = gather_all_metrics();

// Metrics are in Prometheus text format and can be exposed using an HTTP API endpoint
println!("{:?}", gathered_metrics);

Modules§

guard 🔒
metrics 🔒: Contains definitions of metric types.

Macros§

histogram_start_measure: Macro to start a timer measurement on a histogram.

Structs§

GaugeGuard: Creates a RAII guard for a simple gauge metric.
MetricError: Error type for metric operations.
MultiCounter: Represents a vector of named monotonic unsigned integer counters.
MultiGauge: Represents a vector of gauges with floating point values.
MultiGaugeGuard: Creates a RAII guard for a multi-gauge metric.
MultiHistogram: Represents a vector of histograms with floating point values.
SimpleCounter: Represents a simple monotonic unsigned integer counter.
SimpleGauge: Represents a simple gauge with floating point values.
SimpleHistogram: Represents a histogram with floating point values.
SimpleTimer: Represents a timer handle.

Functions§

gather_all_metrics: Gathers all metrics in Prometheus text exposition format.
init_with_provider: Initializes the global metric state with the given exporter and provider.
register_prefix_provider: Registers a meter provider for metric names with the given prefix.

Type Aliases§

MetricResult: Result type for metric operations.