Crate prometheus[−][src]

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.

#[macro_use] extern crate lazy_static;
#[macro_use] extern crate prometheus;
use prometheus::{self, IntCounter, TextEncoder, Encoder};

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.

#[macro_use] extern crate prometheus;
use prometheus::{self, TextEncoder, Encoder};

// 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_gauge	Create a [`Gauge`] and registers to default registry.
register_gauge_vec	Create a [`GaugeVec`] and registers to default registry.
register_histogram	Create a [`Histogram`] and registers to default registry.
register_histogram_vec	Create a [`HistogramVec`] and registers to default 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_gauge	Create an [`IntGauge`] and registers to default registry.
register_int_gauge_vec	Create an [`IntGaugeVec`] and registers to default 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.
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.

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.

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 Definitions

Counter	A `Metric` represents a single numerical value that only ever goes up.
CounterVec	A `Collector` that bundles a set of `Counter`s 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 `Gauge`s 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 integers.
IntCounterVec	The integer version of `CounterVec`. Provides better performance if metric values are all integers.
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.