Crate near_metrics

Expand description

A fork of the lighthouse_metrics crate used to implement prometheus

A wrapper around the prometheus crate that provides a global, lazy_static metrics registry and functions to add and use the following components (more info at Prometheus docs):

Histogram: used with start_timer() and observe_duration() or observe() method to record durations (e.g., block processing time).
IncCounter: used to represent an ideally ever-growing, never-shrinking integer (e.g., number of block processing requests).
IntGauge: used to represent an varying integer (e.g., number of attestations per block).

§Important

Metrics will fail if two items have the same name. All metrics must have a unique name. Because we use a global registry there is no namespace per crate, it’s one big global space.

See the Prometheus naming best practices when choosing metric names.

§Example

use once_cell::sync::Lazy;

use near_metrics::*;

// These metrics are "magically" linked to the global registry defined in `lighthouse_metrics`.
pub static RUN_COUNT: Lazy<IntCounter> = Lazy::new(|| {
    try_create_int_counter(
        "runs_total",
        "Total number of runs",
    )
    .unwrap()
});
pub static CURRENT_VALUE: Lazy<IntGauge> = Lazy::new(|| {
    try_create_int_gauge(
        "current_value",
        "The current value",
    )
    .unwrap()
});
pub static RUN_TIME: Lazy<Histogram> = Lazy::new(|| {
    try_create_histogram(
        "run_seconds",
        "Time taken (measured to high precision)",
    )
    .unwrap()
});

fn main() {
    for i in 0..100 {
        RUN_COUNT.inc();
        let timer = RUN_TIME.start_timer();
        for j in 0..10 {
            CURRENT_VALUE.set(j);
            println!("Howdy partner");
        }
        timer.observe_duration();
    }

    assert_eq!(100, RUN_COUNT.get());
    assert_eq!(9, CURRENT_VALUE.get());
    assert_eq!(100, RUN_TIME.get_sample_count());
    assert!(0.0 < RUN_TIME.get_sample_sum());
}

Structs§

Histogram: A Metric counts individual observations from an event or sample stream in configurable buckets. Similar to a Summary, it also provides a sum of observations and an observation count.
HistogramOpts: A struct that bundles the options for creating a Histogram metric. It is mandatory to set Name and Help to a non-empty string. All other fields are optional and can safely be left at their zero value.
Opts: A struct that bundles the options for creating most Metric types.
TextEncoder: An implementation of an Encoder that converts a MetricFamily proto message into text format.

Traits§

Encoder: An interface for encoding metric families into an underlying wire protocol.

Functions§

do_create_int_counter_vec: Creates ‘IntCounterVec’ - if it has trouble registering to Prometheus it will keep appending a number until the name is unique.
gather: Collect all the metrics for reporting.
try_create_counter: Attempts to crate an Counter, returning Err if the registry does not accept the counter (potentially due to naming conflict).
try_create_gauge: Attempts to crate an Gauge, returning Err if the registry does not accept the gauge (potentially due to naming conflict).
try_create_gauge_vec: Attempts to crate an GaugeVec, returning Err if the registry does not accept the gauge (potentially due to naming conflict).
try_create_histogram: Attempts to crate a Histogram, returning Err if the registry does not accept the counter (potentially due to naming conflict).
try_create_histogram_vec: Attempts to create a HistogramVector, returning Err if the registry does not accept the counter (potentially due to naming conflict).
try_create_int_counter: Attempts to crate an IntCounter, returning Err if the registry does not accept the counter (potentially due to naming conflict).
try_create_int_counter_vec: Attempts to crate an IntCounterVec, returning Err if the registry does not accept the counter (potentially due to naming conflict).
try_create_int_gauge: Attempts to crate an IntGauge, returning Err if the registry does not accept the gauge (potentially due to naming conflict).
try_create_int_gauge_vec: Attempts to crate an IntGaugeVec, returning Err if the registry does not accept the gauge (potentially due to naming conflict).

Type Aliases§

Counter: A Metric represents a single numerical value that only ever goes up.
Gauge: A Metric represents a single numerical value that can arbitrarily go up and down.
GaugeVec: A Collector that bundles a set of Gauges that all share the same Desc, but have different values for their variable labels. This is used if you want to count the same thing partitioned by various dimensions (e.g. number of operations queued, partitioned by user and operation type).
HistogramVec: A Collector that bundles a set of Histograms that all share the same Desc, but have different values for their variable labels. This is used if you want to count the same thing partitioned by various dimensions (e.g. HTTP request latencies, partitioned by status code and method).
IntCounter: The integer version of Counter. Provides better performance if metric values are all positive integers (natural numbers).
IntCounterVec: The integer version of CounterVec. Provides better performance if metric are all positive integers (natural numbers).
IntGauge: The integer version of Gauge. Provides better performance if metric values are all integers.
IntGaugeVec: The integer version of GaugeVec. Provides better performance if metric values are all integers.
Result: A specialized Result type for prometheus.