Crate prometheus

Expand description

The Rust client library for Prometheus.

Use of this library involves a few core concepts:

Metrics like Counters that represent information about your system.
A Registry that Metrics are registered with.
An endpoint that calls gather which returns MetricFamilys through an Encoder.

§Basic Example

use prometheus::{Opts, Registry, Counter, TextEncoder, Encoder};

// Create a Counter.
let counter_opts = Opts::new("test_counter", "test counter help");
let counter = Counter::with_opts(counter_opts).unwrap();

// Create a Registry and register Counter.
let r = Registry::new();
r.register(Box::new(counter.clone())).unwrap();

// Inc.
counter.inc();

// Gather the metrics.
let mut buffer = vec![];
let encoder = TextEncoder::new();
let metric_families = r.gather();
encoder.encode(&metric_families, &mut buffer).unwrap();

// Output to the standard output.
println!("{}", String::from_utf8(buffer).unwrap());

You can find more examples within /examples.

§Static Metrics

This crate supports staticly built metrics. You can use it with lazy_static to quickly build up and collect some metrics.

use prometheus::{self, IntCounter, TextEncoder, Encoder};

use lazy_static::lazy_static;
use prometheus::register_int_counter;

lazy_static! {
    static ref HIGH_FIVE_COUNTER: IntCounter =
        register_int_counter!("highfives", "Number of high fives received").unwrap();
}

HIGH_FIVE_COUNTER.inc();
assert_eq!(HIGH_FIVE_COUNTER.get(), 1);

By default, this registers with a default registry. To make a report, you can call gather. This will return a family of metrics you can then feed through an Encoder and report to Promethus.

use prometheus::{self, TextEncoder, Encoder};

use lazy_static::lazy_static;
use prometheus::register_int_counter;

// Register & measure some metrics.

let mut buffer = Vec::new();
let encoder = TextEncoder::new();

// Gather the metrics.
let metric_families = prometheus::gather();
// Encode them to send.
encoder.encode(&metric_families, &mut buffer).unwrap();

let output = String::from_utf8(buffer.clone()).unwrap();
const EXPECTED_OUTPUT: &'static str = "# HELP highfives Number of high fives received\n# TYPE highfives counter\nhighfives 1\n";
assert!(output.starts_with(EXPECTED_OUTPUT));

See prometheus_static_metric for additional functionality.

§Features

This library supports four features:

gen: To generate protobuf client with the latest protobuf version instead of using the pre-generated client.
nightly: Enable nightly only features.
process: For collecting process info.
push: Enable push support.

Modules§

core: Core traits and types.
local: Unsync local metrics, provides better performance.
proto: Non-generated version of required structures provided by the protobuf. This version is used when the protobuf feature is turned off.

Macros§

histogram_opts: Create a HistogramOpts.
labels: Create labels with specified name-value pairs.
opts: Create an Opts.
register_counter: Create a Counter and registers to default registry.
register_counter_vec: Create a CounterVec and registers to default registry.
register_counter_vec_with_registry: Create a CounterVec and registers to a custom registry.
register_counter_with_registry: Create a Counter and registers to a custom registry.
register_gauge: Create a Gauge and registers to default registry.
register_gauge_vec: Create a GaugeVec and registers to default registry.
register_gauge_vec_with_registry: Create a GaugeVec and registers to a custom registry.
register_gauge_with_registry: Create a Gauge and registers to a custom registry.
register_histogram: Create a Histogram and registers to default registry.
register_histogram_vec: Create a HistogramVec and registers to default registry.
register_histogram_vec_with_registry: Create a HistogramVec and registers to a custom registry.
register_histogram_with_registry: Create a Histogram and registers to a custom registry.
register_int_counter: Create an IntCounter and registers to default registry.
register_int_counter_vec: Create an IntCounterVec and registers to default registry.
register_int_counter_vec_with_registry: Create an IntCounterVec and registers to a custom registry.
register_int_counter_with_registry: Create an IntCounter and registers to a custom registry.
register_int_gauge: Create an IntGauge and registers to default registry.
register_int_gauge_vec: Create an IntGaugeVec and registers to default registry.
register_int_gauge_vec_with_registry: Create an IntGaugeVec and registers to a custom registry.
register_int_gauge_with_registry: Create an IntGauge and registers to a custom registry.

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.
HistogramTimer: Timer to measure and record the duration of an event.
Opts: A struct that bundles the options for creating most Metric types.
PullingGauge: A Gauge that returns the value from a provided function on every collect run.
Registry: A struct for registering Prometheus collectors, collecting their metrics, and gathering them into MetricFamilies for exposition.
TextEncoder: An implementation of an Encoder that converts a MetricFamily proto message into text format.

Enums§

Error: The error types for prometheus.

Constants§

DEFAULT_BUCKETS: The default Histogram buckets. The default buckets are tailored to broadly measure the response time (in seconds) of a network service. Most likely, however, you will be required to define buckets customized to your use case.
TEXT_FORMAT: The text format of metric family.

Traits§

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

Functions§

default_registry: Default registry (global static).
exponential_buckets: Create count buckets, where the lowest bucket has an upper bound of start and each following bucket’s upper bound is factor times the previous bucket’s upper bound. The final +Inf bucket is not counted and not included in the returned slice. The returned slice is meant to be used for the Buckets field of HistogramOpts.
gather: Return all MetricFamily of DEFAULT_REGISTRY.
linear_buckets: Create count buckets, each width wide, where the lowest bucket has an upper bound of start. The final +Inf bucket is not counted and not included in the returned slice. The returned slice is meant to be used for the Buckets field of HistogramOpts.
register: Registers a new Collector to be included in metrics collection. It returns an error if the descriptors provided by the Collector are invalid or if they - in combination with descriptors of already registered Collectors - do not fulfill the consistency and uniqueness criteria described in the Desc documentation.
unregister: Unregisters the Collector that equals the Collector passed in as an argument. (Two Collectors are considered equal if their Describe method yields the same set of descriptors.) The function returns an error if a Collector was not registered.

Type Aliases§

Counter: A Metric represents a single numerical value that only ever goes up.
CounterVec: A Collector that bundles a set of Counters 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 HTTP requests, partitioned by response code and method).
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.

Crate prometheusCopy item path