https://github.com/lambdalisue/rs-metrics-process
⏱ Cross-platform Prometheus style process metrics collector of metrics crate
https://github.com/lambdalisue/rs-metrics-process
cross-platform metrics process-metrics prometheus prometheus-metrics
Last synced: 3 months ago
JSON representation
⏱ Cross-platform Prometheus style process metrics collector of metrics crate
- Host: GitHub
- URL: https://github.com/lambdalisue/rs-metrics-process
- Owner: lambdalisue
- License: mit
- Created: 2022-08-20T14:15:12.000Z (almost 3 years ago)
- Default Branch: main
- Last Pushed: 2025-03-19T08:11:19.000Z (3 months ago)
- Last Synced: 2025-03-28T15:09:16.610Z (3 months ago)
- Topics: cross-platform, metrics, process-metrics, prometheus, prometheus-metrics
- Language: Rust
- Homepage: https://docs.rs/metrics-process/latest/metrics_process/
- Size: 171 KB
- Stars: 36
- Watchers: 2
- Forks: 10
- Open Issues: 3
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
[](https://crates.io/crates/metrics-process)
[](https://docs.rs/metrics-process)
[](./LICENSE)
[](https://github.com/lambdalisue/rs-metrics-process/actions/workflows/build.yml)
[](https://github.com/lambdalisue/rs-metrics-process/actions/workflows/test.yml)
[](https://github.com/lambdalisue/rs-metrics-process/actions/workflows/audit.yml)
# ⏱ metrics-process
This crate provides a [Prometheus]-style [process metrics] collector for the
[metrics] crate, supporting Linux, macOS, Windows, and FreeBSD. 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.
[Prometheus]: https://prometheus.io/
[process metrics]: https://prometheus.io/docs/instrumenting/writing_clientlibs/#process-metrics
[metrics]: https://crates.io/crates/metrics
## 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 that code for OpenBSD exists but is not
tested and we cannot guarantee its correctness.
> [!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`.
[client_golang]: https://github.com/prometheus/client_golang
## Usage
Use this crate with [metrics-exporter-prometheus] as an exporter like:
[metrics-exporter-prometheus]: https://crates.io/crates/metrics-exporter-prometheus
```rust,no_run
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:
[axum]: https://crates.io/crates/axum
```rust,no_run
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. |
| `metrics-rs` (enabled by default) | Enables the [metrics] integration. Can be removed to reduce dependencies if unused.
# License
The code follows the MIT license written in [LICENSE](./LICENSE). Contributors
need to agree that any modifications sent to this repository follow the license.