Crate prometheus[][src]

The Rust client library for Prometheus.

Use of this library involves a few core concepts:

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:

Modules

core

Core traits and types.

local

Unsync local metrics, provides better performance.

proto

Protocol buffers format of metrics.

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

BasicAuthentication

BasicAuthentication holder for supporting push to Pushgateway endpoints using Basic access authentication. Can be passed to any push_metrics method.

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.

ProtobufEncoder

An implementation of an Encoder that converts a MetricFamily proto message into the binary wire format of protobuf.

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.

PROTOBUF_FORMAT

The protocol buffer format of metric family.

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.

hostname_grouping_key

hostname_grouping_key returns a label map with the only entry {instance=“”}. This can be conveniently used as the grouping parameter if metrics should be pushed with the hostname as label. The returned map is created upon each call so that the caller is free to add more labels to the map.

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.

push_add_collector

push_add_collector works like push_add_metrics, it collects from the provided collectors. It is a convenient way to push only a few metrics.

push_add_metrics

push_add_metrics works like push_metrics, but only previously pushed metrics with the same name (and the same job and other grouping labels) will be replaced. (It uses HTTP method ‘POST’ to push to the Pushgateway.)

push_collector

push_collector push metrics collected from the provided collectors. It is a convenient way to push only a few metrics.

push_metrics

push_metrics pushes all gathered metrics to the Pushgateway specified by url, using the provided job name and the (optional) further grouping labels (the grouping map may be nil). See the Pushgateway documentation for detailed implications of the job and other grouping labels. Neither the job name nor any grouping label value may contain a “/”. The metrics pushed must not contain a job label of their own nor any of the grouping labels.

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 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 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.