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
//! # Metrics Gauge Interface //! //! `Gauge`s support `set(value, label_set)`. `Gauge` metrics express //! a pre-calculated value that is either `set` by explicit instrumentation //! or observed through a callback. Generally, this kind of metric should //! be used when the metric cannot be expressed as a sum or because the //! measurement interval is arbitrary. Use this kind of metric when the //! measurement is not a quantity, and the sum and event count are not of //! interest. //! //! `Gauge`s are defined as `monotonic = false` by default, meaning that new //! values are permitted to make positive or negative changes to the //! gauge. There is no restriction on the sign of the input for gauges. //! //! As an option, gauges can be declared as `with_monotonic(true)`, in which case //! successive values are expected to rise monotonically. `monotonic = true` //! gauges are useful in reporting computed cumulative sums, allowing an //! application to compute a current value and report it, without //! remembering the last-reported value in order to report an increment. use crate::api::metrics; /// An interface for recording values where the metric cannot be expressed /// as a sum or because the measurement interval is arbitrary. pub trait Gauge<T, LS>: metrics::Instrument<LS> where T: Into<metrics::value::MeasurementValue>, LS: metrics::LabelSet, { /// The handle type for the implementing `Gauge`. type Handle: GaugeHandle<T>; /// Creates a `Measurement` object to be used by a `Meter` when batch recording. fn measurement(&self, value: T) -> metrics::Measurement<LS>; /// Creates a handle for this gauge. The labels should contain the /// keys and values for each key specified in the `LabelSet`. /// /// If the labels do not contain a value for the key specified in the /// `LabelSet`, then the missing value will be treated as unspecified. fn acquire_handle(&self, labels: &LS) -> Self::Handle; /// Assigns the passed value to the value of the gauge. The labels /// should contain the keys and values for each key specified in /// the `LabelSet`. /// /// If the labels do not contain a value for the key specified in the /// `LabelSet`, then the missing value will be treated as unspecified. fn set(&self, value: T, label_set: &LS) { self.record_one(value.into(), label_set) } } /// `GaugeHandle` is a handle for `Gauge` instances. /// /// It allows for repeated `set` calls for a pre-determined `LabelSet`. pub trait GaugeHandle<T>: metrics::InstrumentHandle where T: Into<metrics::value::MeasurementValue>, { /// Set works by calling the underlying `record_one` method /// available because this trait also implements `InstrumentHandle`. fn set(&self, value: T) { self.record_one(value.into()) } }