Skip to content

lambdalisue/rs-metrics-process

Folders and files

NameName
Last commit message
Last commit date

Latest commit

 
 
 
 
 
 
 
 
 
 
 
 
 
 
 

Repository files navigation

crates.io docs.rs MIT License Build Test Audit

⏱ metrics-process

This crate provides a Prometheus-style process metrics collector for the metrics crate, supporting Linux, macOS, Windows, FreeBSD, and OpenBSD. The original collector code was manually rewritten in Rust from the official Prometheus client for Go (client_golang), *BSD support code was written from scratch.

Supported Metrics

This crate supports the following metrics provided by Prometheus for process metrics.

Metric name Help string
process_cpu_seconds_total Total user and system CPU time spent in seconds.
process_open_fds Number of open file descriptors.
process_max_fds Maximum number of open file descriptors.
process_virtual_memory_bytes Virtual memory size in bytes.
process_virtual_memory_max_bytes Maximum amount of virtual memory available in bytes.
process_resident_memory_bytes Resident memory size in bytes.
process_heap_bytes Process heap size in bytes.
process_start_time_seconds Start time of the process since the Unix epoch in seconds.
process_threads Number of OS threads in the process.

For each platform, it is equivalent to what the official Prometheus client for Go (client_golang) provides.

Note

Prior to version 2.0.0, the process_cpu_seconds_total metric was Gauge instead of Counter. Enable use-gauge-on-cpu-seconds-total feature to use the previous behavior.

Metric name Linux macOS Windows FreeBSD OpenBSD
process_cpu_seconds_total x x x x x
process_open_fds x x x x
process_max_fds x x x x x
process_virtual_memory_bytes x x x x
process_virtual_memory_max_bytes x x x
process_resident_memory_bytes x x x x x
process_heap_bytes
process_start_time_seconds x x x x x
process_threads x x x

Note

If you only need to compile this crate on non-supported platforms, you can use the dummy feature. Enabling this feature activates a dummy collector, which returns an empty Metrics.

Usage

Use this crate with metrics-exporter-prometheus as an exporter like:

use std::thread;
use std::time::{Duration, Instant};

use metrics_exporter_prometheus::PrometheusBuilder;
use metrics_process::Collector;

let builder = PrometheusBuilder::new();
builder
    .install()
    .expect("failed to install Prometheus recorder");

let collector = Collector::default();
// Call `describe()` method to register help string.
collector.describe();

loop {
    // Periodically call `collect()` method to update information.
    collector.collect();
    thread::sleep(Duration::from_millis(750));
}

Or with axum (or any web application framework you like) to collect metrics whenever the /metrics endpoint is invoked like:

use axum::{routing::get, Router};
use metrics_exporter_prometheus::PrometheusBuilder;
use metrics_process::Collector;
use tokio::net::TcpListener;

#[tokio::main]
async fn main() {
    let builder = PrometheusBuilder::new();
    let handle = builder
        .install_recorder()
        .expect("failed to install Prometheus recorder");

    let collector = Collector::default();
    // Call `describe()` method to register help string.
    collector.describe();

    let app = Router::new().route(
        "/metrics",
        get(move || {
            // Collect information just before handling '/metrics'
            collector.collect();
            std::future::ready(handle.render())
        }),
    );
    let listener = TcpListener::bind("127.0.0.1:3000").await.unwrap();
    axum::serve(listener, app).await.unwrap();
}

Features

This crate offers the following features:

Feature Name Description
dummy Enables a dummy collector that returns an empty Metrics on non-supported platforms.
use-gauge-on-cpu-seconds-total Use a Gauge on process_cpu_seconds_total metrics instead of Counter to represent f64 value. This is a previous behavior prior to version 2.0.0.

License

The code follows the MIT license written in LICENSE. Contributors need to agree that any modifications sent to this repository follow the license.