FastMetrics

A pure-Rust implementation of the OpenMetrics specification for transmitting cloud-native metrics at scale, and it's compatible with Prometheus.

Features

Full support for OpenMetrics specification
Fast encoding in both text and (optional) protobuf exposition format
- Text
  - Prometheus text: 0.0.4, 1.0.0
  - OpenMetrics text: 0.0.1, 1.0.0
  - V1 escaping schemes: allow-utf-8, underscores, dots, values
- Protobuf
  - Prometheus protobuf schema
  - OpenMetrics protobuf schema
Customizable metric types (currently a set of commonly used metric types are provided)
Hierarchical metric organization with namespaces and subsystems
Support for variable and constant labels
Derive macros to simplify code (e.g., like registering metrics, label handling, etc.)

Usage

use fastmetrics::{
    derive::*,
    error::Result,
    format::text::{self, TextProfile},
    metrics::{counter::Counter, family::Family},
    registry::*,
};

// Define label types
// Need to enable `derive` feature to use `#[derive(LabelSet)]`
// or `#[derive(EncodeLabelSet, LabelSetSchema)]`
#[derive(Clone, Eq, PartialEq, Hash, LabelSet)]
struct Labels {
    method: Method,
    status: u16,
}

// Need to enable `derive` feature to use `#[derive(EncodeLabelValue)]`
#[derive(Clone, Eq, PartialEq, Hash, EncodeLabelValue)]
enum Method {
    Get,
    Put,
}

// Need to enable `derive` feature to use `#[derive(Register)]`
#[derive(Default, Register)]
struct Metrics {
    /// Total requests processed
    requests: Counter,
    /// Total HTTP requests
    http_requests: Family<Labels, Counter>,
}

fn main() -> Result<()> {
    // Create a registry with a namespace and some constant labels
    let mut registry = Registry::builder()
        .with_namespace("myapp")
        .with_const_labels([("env", "prod")])
        .build()?;

    // Register metrics
    let metrics = Metrics::default();
    metrics.register(&mut registry)?;

    // Update the simple counter
    metrics.requests.inc();
    assert_eq!(metrics.requests.total(), 1);

    // Update the counter family
    let labels = Labels { method: Method::Get, status: 200 };
    metrics.http_requests.with_or_new(&labels, |req| req.inc());
    assert_eq!(metrics.http_requests.with(&labels, |req| req.total()), Some(1));

    // Export metrics in text format
    let mut output = String::new();
    text::encode(&mut output, &registry, TextProfile::default())?;
    println!("{}", output);

    Ok(())
}

See documentation and examples for more details.

Performance

See benchmarks for more details

Acknowledgment

I drew a lot of inspiration from the following libraries, retaining the designs I thought were good and experimenting with some different ones.

prometheus/client_golang: Official prometheus client library for Golang applications.
prometheus/client_rust: Official prometheus client library for Rust applications.
tikv/rust-prometheus: Another prometheus instrumentation library for Rust applications.

License