metriken-core 0.3.0

A fast and lightweight metrics library
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
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135

use std::collections::HashMap;

use crate::Window;

/// Trait for histogram metrics that can produce snapshots.
///
/// Implemented by both `AtomicHistogram` (for recording individual events)
/// and `RwLockHistogram` (for bulk updates from pre-aggregated data).
/// Exposition code can use this trait without knowing which variant it has.
pub trait HistogramMetric: Send + Sync + 'static {
    /// Return the histogram configuration.
    fn config(&self) -> histogram::Config;

    /// Load a snapshot of the histogram.
    ///
    /// Returns `None` if the histogram has never been written to.
    fn load(&self) -> Option<histogram::Histogram>;
}

/// Trait for a group of counter metrics with per-entry metadata.
///
/// Counter groups store a dense array of `u64` values indexed by `usize`,
/// with sparse metadata attached to individual entries.
pub trait CounterGroupMetric: Send + Sync + 'static {
    /// Return the number of entries in this group.
    fn entries(&self) -> usize;

    /// Load the value of the counter at `idx`.
    fn counter_value(&self, idx: usize) -> Option<u64>;

    /// Load all counter values as a snapshot.
    fn load_counters(&self) -> Option<Vec<u64>>;

    /// Load metadata for the entry at `idx`.
    fn load_metadata(&self, idx: usize) -> Option<HashMap<String, String>>;

    /// Snapshot all metadata.
    fn metadata_snapshot(&self) -> Vec<(usize, HashMap<String, String>)>;

    /// Load the acquisition window recorded for the entry at `idx`, if any.
    /// Default: none — general groups do not record windows.
    fn load_window(&self, _idx: usize) -> Option<Window> {
        None
    }

    /// Snapshot all per-entry acquisition windows. Default: empty.
    fn window_snapshot(&self) -> Vec<(usize, Window)> {
        Vec::new()
    }

    /// Load the counter at `idx` and its acquisition window as a pair.
    ///
    /// Default: separate `counter_value` and `load_window` reads — **not**
    /// atomic. Windowed groups override this to read the pair under one lock so
    /// exposition never sees a torn `(value, window)` pair.
    fn load_with_window(&self, idx: usize) -> (Option<u64>, Option<Window>) {
        (self.counter_value(idx), self.load_window(idx))
    }
}

/// Trait for a group of gauge metrics with per-entry metadata.
///
/// Gauge groups store a dense array of `i64` values indexed by `usize`,
/// with sparse metadata attached to individual entries.
pub trait GaugeGroupMetric: Send + Sync + 'static {
    /// Return the number of entries in this group.
    fn entries(&self) -> usize;

    /// Load the value of the gauge at `idx`.
    fn gauge_value(&self, idx: usize) -> Option<i64>;

    /// Load all gauge values as a snapshot.
    fn load_gauges(&self) -> Option<Vec<i64>>;

    /// Load metadata for the entry at `idx`.
    fn load_metadata(&self, idx: usize) -> Option<HashMap<String, String>>;

    /// Snapshot all metadata.
    fn metadata_snapshot(&self) -> Vec<(usize, HashMap<String, String>)>;

    /// Load the acquisition window recorded for the entry at `idx`, if any.
    /// Default: none — general groups do not record windows.
    fn load_window(&self, _idx: usize) -> Option<Window> {
        None
    }

    /// Snapshot all per-entry acquisition windows. Default: empty.
    fn window_snapshot(&self) -> Vec<(usize, Window)> {
        Vec::new()
    }

    /// Load the gauge at `idx` and its acquisition window as a pair.
    ///
    /// Default: separate `gauge_value` and `load_window` reads — **not**
    /// atomic. Windowed groups override this to read the pair under one lock.
    fn load_with_window(&self, idx: usize) -> (Option<i64>, Option<Window>) {
        (self.gauge_value(idx), self.load_window(idx))
    }
}

/// Trait for a group of histogram metrics with per-entry metadata.
///
/// Histogram groups store a dense array of histograms (all sharing the same
/// configuration) indexed by `usize`, with sparse metadata attached to
/// individual entries.
pub trait HistogramGroupMetric: Send + Sync + 'static {
    /// Return the number of entries in this group.
    fn entries(&self) -> usize;

    /// Return the histogram configuration shared by all entries.
    fn config(&self) -> histogram::Config;

    /// Load a snapshot of the histogram at `idx`.
    fn load_histogram(&self, idx: usize) -> Option<histogram::Histogram>;

    /// Load snapshots of all histograms.
    fn load_all_histograms(&self) -> Option<Vec<histogram::Histogram>>;

    /// Load metadata for the entry at `idx`.
    fn load_metadata(&self, idx: usize) -> Option<HashMap<String, String>>;

    /// Snapshot all metadata.
    fn metadata_snapshot(&self) -> Vec<(usize, HashMap<String, String>)>;

    /// Load the acquisition window recorded for the entry at `idx`, if any.
    /// Default: none — general groups do not record windows.
    fn load_window(&self, _idx: usize) -> Option<Window> {
        None
    }

    /// Snapshot all per-entry acquisition windows. Default: empty.
    fn window_snapshot(&self) -> Vec<(usize, Window)> {
        Vec::new()
    }
}