folk_api/
metrics.rs

1//! Metrics registration. Plugins create metric families and update counters,
2//! gauges, and histograms.
3
4use std::sync::Arc;
5
6/// Single counter handle (one specific label combination).
7pub trait Counter: Send + Sync + 'static {
8    fn inc(&self);
9    /// Increment the counter by `v`.
10    ///
11    /// Implementations must use **saturating** arithmetic: calling `inc_by`
12    /// when the counter is at or near its maximum value must not wrap around
13    /// to zero. Saturation at the maximum representable value is acceptable.
14    fn inc_by(&self, v: u64);
15    fn get(&self) -> u64;
16}
17
18/// Single gauge handle (one specific label combination).
19pub trait Gauge: Send + Sync + 'static {
20    fn set(&self, v: i64);
21    fn inc(&self);
22    fn dec(&self);
23    fn get(&self) -> i64;
24}
25
26/// Single histogram handle (one specific label combination).
27pub trait Histogram: Send + Sync + 'static {
28    fn observe(&self, v: f64);
29}
30
31/// A counter metric family — use `with_labels` to get a concrete handle.
32pub trait CounterVec: Send + Sync + 'static {
33    fn with_labels(&self, labels: &[&str]) -> Arc<dyn Counter>;
34}
35
36pub trait GaugeVec: Send + Sync + 'static {
37    fn with_labels(&self, labels: &[&str]) -> Arc<dyn Gauge>;
38}
39
40pub trait HistogramVec: Send + Sync + 'static {
41    fn with_labels(&self, labels: &[&str]) -> Arc<dyn Histogram>;
42}
43
44/// Plugins register metric families here. Observers render them.
45pub trait MetricsRegistry: Send + Sync + 'static {
46    fn counter_vec(&self, name: &str, help: &str, label_keys: &[&str]) -> Arc<dyn CounterVec>;
47    fn gauge_vec(&self, name: &str, help: &str, label_keys: &[&str]) -> Arc<dyn GaugeVec>;
48    fn histogram_vec(&self, name: &str, help: &str, label_keys: &[&str]) -> Arc<dyn HistogramVec>;
49
50    /// Render all registered metrics in Prometheus text exposition format.
51    fn render(&self) -> String;
52}
folk_api/metrics.rs

folk_api/
metrics.rs
