metrics_util/
debugging.rs

1//! Debugging utilities.
2//!
3//! While these utilities are primarily designed to help aid with testing and debugging of exporters
4//! and core parts of the `metrics` ecosystem, they can be beneficial for in-process collecting of
5//! metrics in some limited cases.
6
7use std::{
8    collections::HashMap,
9    fmt::Debug,
10    hash::Hash,
11    sync::{atomic::Ordering, Arc, Mutex},
12};
13
14use crate::{
15    kind::MetricKind,
16    registry::{AtomicStorage, Registry},
17    CompositeKey,
18};
19
20use indexmap::IndexMap;
21use metrics::{
22    Counter, Gauge, Histogram, Key, KeyName, Metadata, Recorder, SetRecorderError, SharedString,
23    Unit,
24};
25use ordered_float::OrderedFloat;
26
27/// A composite key name that stores both the metric key name and the metric kind.
28#[derive(Clone, Debug, Eq, Hash, PartialEq, PartialOrd, Ord)]
29struct CompositeKeyName(MetricKind, KeyName);
30
31impl CompositeKeyName {
32    /// Creates a new `CompositeKeyName`.
33    pub const fn new(kind: MetricKind, key_name: KeyName) -> CompositeKeyName {
34        CompositeKeyName(kind, key_name)
35    }
36}
37
38/// A point-in-time snapshot of all metrics in [`DebuggingRecorder`].
39#[derive(Debug)]
40pub struct Snapshot(Vec<(CompositeKey, Option<Unit>, Option<SharedString>, DebugValue)>);
41
42impl Snapshot {
43    /// Converts this snapshot to a mapping of metric data, keyed by the metric key itself.
44    #[allow(clippy::mutable_key_type)]
45    pub fn into_hashmap(
46        self,
47    ) -> HashMap<CompositeKey, (Option<Unit>, Option<SharedString>, DebugValue)> {
48        self.0
49            .into_iter()
50            .map(|(k, unit, desc, value)| (k, (unit, desc, value)))
51            .collect::<HashMap<_, _>>()
52    }
53
54    /// Converts this snapshot to a vector of metric data tuples.
55    pub fn into_vec(self) -> Vec<(CompositeKey, Option<Unit>, Option<SharedString>, DebugValue)> {
56        self.0
57    }
58}
59
60/// A point-in-time value for a metric exposing raw values.
61#[derive(Debug, PartialEq, Eq, Hash)]
62pub enum DebugValue {
63    /// Counter.
64    Counter(u64),
65    /// Gauge.
66    Gauge(OrderedFloat<f64>),
67    /// Histogram.
68    Histogram(Vec<OrderedFloat<f64>>),
69}
70
71#[derive(Debug)]
72struct Inner {
73    registry: Registry<Key, AtomicStorage>,
74    seen: Mutex<IndexMap<CompositeKey, ()>>,
75    metadata: Mutex<IndexMap<CompositeKeyName, (Option<Unit>, SharedString)>>,
76}
77
78impl Inner {
79    fn new() -> Self {
80        Self {
81            registry: Registry::atomic(),
82            seen: Mutex::new(IndexMap::new()),
83            metadata: Mutex::new(IndexMap::new()),
84        }
85    }
86}
87
88/// Captures point-in-time snapshots of [`DebuggingRecorder`].
89#[derive(Clone, Debug)]
90pub struct Snapshotter {
91    inner: Arc<Inner>,
92}
93
94impl Snapshotter {
95    /// Takes a snapshot of the recorder.
96    pub fn snapshot(&self) -> Snapshot {
97        let mut snapshot = Vec::new();
98
99        let counters = self.inner.registry.get_counter_handles();
100        let gauges = self.inner.registry.get_gauge_handles();
101        let histograms = self.inner.registry.get_histogram_handles();
102
103        let seen = self.inner.seen.lock().expect("seen lock poisoned").clone();
104        let metadata = self.inner.metadata.lock().expect("metadata lock poisoned").clone();
105
106        for (ck, _) in seen.into_iter() {
107            let value = match ck.kind() {
108                MetricKind::Counter => {
109                    counters.get(ck.key()).map(|c| DebugValue::Counter(c.load(Ordering::SeqCst)))
110                }
111                MetricKind::Gauge => gauges.get(ck.key()).map(|g| {
112                    let value = f64::from_bits(g.load(Ordering::SeqCst));
113                    DebugValue::Gauge(value.into())
114                }),
115                MetricKind::Histogram => histograms.get(ck.key()).map(|h| {
116                    let mut values = Vec::new();
117                    h.clear_with(|xs| values.extend(xs.iter().map(|f| OrderedFloat::from(*f))));
118                    DebugValue::Histogram(values)
119                }),
120            };
121
122            let ckn = CompositeKeyName::new(ck.kind(), ck.key().name().to_string().into());
123            let (unit, desc) = metadata
124                .get(&ckn)
125                .map(|(u, d)| (u.to_owned(), Some(d.to_owned())))
126                .unwrap_or_else(|| (None, None));
127
128            // If there's no value for the key, that means the metric was only ever described, and
129            // not registered, so don't emit it.
130            if let Some(value) = value {
131                snapshot.push((ck, unit, desc, value));
132            }
133        }
134
135        Snapshot(snapshot)
136    }
137}
138
139/// A simplistic recorder that can be installed and used for debugging or testing.
140///
141/// Callers can easily take snapshots of the metrics at any given time and get access
142/// to the raw values.
143#[derive(Debug)]
144pub struct DebuggingRecorder {
145    inner: Arc<Inner>,
146}
147
148impl DebuggingRecorder {
149    /// Creates a new `DebuggingRecorder`.
150    pub fn new() -> DebuggingRecorder {
151        DebuggingRecorder { inner: Arc::new(Inner::new()) }
152    }
153
154    /// Gets a `Snapshotter` attached to this recorder.
155    pub fn snapshotter(&self) -> Snapshotter {
156        Snapshotter { inner: Arc::clone(&self.inner) }
157    }
158
159    fn describe_metric(&self, rkey: CompositeKeyName, unit: Option<Unit>, desc: SharedString) {
160        let mut metadata = self.inner.metadata.lock().expect("metadata lock poisoned");
161        let (uentry, dentry) = metadata.entry(rkey).or_insert((None, desc.to_owned()));
162        if unit.is_some() {
163            *uentry = unit;
164        }
165        *dentry = desc;
166    }
167
168    fn track_metric(&self, ckey: CompositeKey) {
169        let mut seen = self.inner.seen.lock().expect("seen lock poisoned");
170        seen.insert(ckey, ());
171    }
172
173    /// Installs this recorder as the global recorder.
174    pub fn install(self) -> Result<(), SetRecorderError<Self>> {
175        metrics::set_global_recorder(self)
176    }
177}
178
179impl Recorder for DebuggingRecorder {
180    fn describe_counter(&self, key: KeyName, unit: Option<Unit>, description: SharedString) {
181        let ckey = CompositeKeyName::new(MetricKind::Counter, key);
182        self.describe_metric(ckey, unit, description);
183    }
184
185    fn describe_gauge(&self, key: KeyName, unit: Option<Unit>, description: SharedString) {
186        let ckey = CompositeKeyName::new(MetricKind::Gauge, key);
187        self.describe_metric(ckey, unit, description);
188    }
189
190    fn describe_histogram(&self, key: KeyName, unit: Option<Unit>, description: SharedString) {
191        let ckey = CompositeKeyName::new(MetricKind::Histogram, key);
192        self.describe_metric(ckey, unit, description);
193    }
194
195    fn register_counter(&self, key: &Key, _metadata: &Metadata<'_>) -> Counter {
196        let ckey = CompositeKey::new(MetricKind::Counter, key.clone());
197        self.track_metric(ckey);
198
199        self.inner.registry.get_or_create_counter(key, |c| Counter::from_arc(c.clone()))
200    }
201
202    fn register_gauge(&self, key: &Key, _metadata: &Metadata<'_>) -> Gauge {
203        let ckey = CompositeKey::new(MetricKind::Gauge, key.clone());
204        self.track_metric(ckey);
205
206        self.inner.registry.get_or_create_gauge(key, |g| Gauge::from_arc(g.clone()))
207    }
208
209    fn register_histogram(&self, key: &Key, _metadata: &Metadata<'_>) -> Histogram {
210        let ckey = CompositeKey::new(MetricKind::Histogram, key.clone());
211        self.track_metric(ckey);
212
213        self.inner.registry.get_or_create_histogram(key, |h| Histogram::from_arc(h.clone()))
214    }
215}
216
217impl Default for DebuggingRecorder {
218    fn default() -> Self {
219        DebuggingRecorder::new()
220    }
221}
metrics_util/debugging.rs

metrics_util/
debugging.rs
