Crate prometheus
source ·Expand description
The Rust client library for Prometheus.
Use of this library involves a few core concepts:
-
Metric
s likeCounter
s that represent information about your system. -
An endpoint that calls
gather
which returnsMetricFamily
s through anEncoder
.
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 traits and types.
- Unsync local metrics, provides better performance.
- Non-generated version of required structures provided by the protobuf. This version is used when the
protobuf
feature is turned off.
Macros
- Create a
HistogramOpts
. - Create labels with specified name-value pairs.
- Create an
Opts
. - Create a
Counter
and registers to default registry. - Create a
CounterVec
and registers to default registry. - Create a
CounterVec
and registers to a custom registry. - Create a
Counter
and registers to a custom registry. - Create a
Gauge
and registers to default registry. - Create a
GaugeVec
and registers to default registry. - Create a
GaugeVec
and registers to a custom registry. - Create a
Gauge
and registers to a custom registry. - Create a
Histogram
and registers to default registry. - Create a
HistogramVec
and registers to default registry. - Create a
HistogramVec
and registers to default registry. - Create a
Histogram
and registers to a custom registry. - Create an
IntCounter
and registers to default registry. - Create an
IntCounterVec
and registers to default registry. - Create an
IntCounterVec
and registers to a custom registry. - Create an
IntCounter
and registers to a custom registry. - Create an
IntGauge
and registers to default registry. - Create an
IntGaugeVec
and registers to default registry. - Create an
IntGaugeVec
and registers to a custom registry. - Create an
IntGauge
and registers to a custom registry.
Structs
- 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. - Timer to measure and record the duration of an event.
- A struct that bundles the options for creating most
Metric
types. - A struct for registering Prometheus collectors, collecting their metrics, and gathering them into
MetricFamilies
for exposition. - An implementation of an
Encoder
that converts aMetricFamily
proto message into text format.
Enums
- The error types for prometheus.
Constants
- 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. - The text format of metric family.
Traits
- An interface for encoding metric families into an underlying wire protocol.
Functions
- Default registry (global static).
- Create
count
buckets, where the lowest bucket has an upper bound ofstart
and each following bucket’s upper bound isfactor
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 ofHistogramOpts
. - Return all
MetricFamily
ofDEFAULT_REGISTRY
. - Create
count
buckets, eachwidth
wide, where the lowest bucket has an upper bound ofstart
. 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 ofHistogramOpts
. - Registers a new
Collector
to be included in metrics collection. It returns an error if the descriptors provided by theCollector
are invalid or if they - in combination with descriptors of already registered Collectors - do not fulfill the consistency and uniqueness criteria described in theDesc
documentation.
Type Definitions
- A
Metric
represents a single numerical value that only ever goes up. - A
Metric
represents a single numerical value that can arbitrarily go up and down. - The integer version of
Counter
. Provides better performance if metric values are all positive integers (natural numbers). - The integer version of
CounterVec
. Provides better performance if metric are all positive integers (natural numbers). - The integer version of
Gauge
. Provides better performance if metric values are all integers. - The integer version of
GaugeVec
. Provides better performance if metric values are all integers. - A specialized Result type for prometheus.