Crate tokio_metrics

Monitor key metrics of tokio tasks and runtimes.

Monitoring task metrics

Monitor key metrics of tokio tasks.

In the below example, a TaskMonitor is constructed and used to instrument three worker tasks; meanwhile, a fourth task prints metrics in 500ms intervals:

use std::time::Duration;

#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error + Send + Sync>> {
    // construct a metrics taskmonitor
    let metrics_monitor = tokio_metrics::TaskMonitor::new();

    // print task metrics every 500ms
    {
        let metrics_monitor = metrics_monitor.clone();
        tokio::spawn(async move {
            for interval in metrics_monitor.intervals() {
                // pretty-print the metric interval
                println!("{:?}", interval);
                // wait 500ms
                tokio::time::sleep(Duration::from_millis(500)).await;
            }
        });
    }

    // instrument some tasks and await them
    // note that the same taskmonitor can be used for multiple tasks
    tokio::join![
        metrics_monitor.instrument(do_work()),
        metrics_monitor.instrument(do_work()),
        metrics_monitor.instrument(do_work())
    ];

    Ok(())
}

async fn do_work() {
    for _ in 0..25 {
        tokio::task::yield_now().await;
        tokio::time::sleep(Duration::from_millis(100)).await;
    }
}

Monitoring runtime metrics (unstable)

Monitor key metrics of a tokio runtime. This functionality requires tokio_unstable and the crate feature rt.

In the below example, a RuntimeMonitor is constructed and three tasks are spawned and awaited; meanwhile, a fourth task prints metrics in 500ms intervals:

use std::time::Duration;

#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error + Send + Sync>> {
    let handle = tokio::runtime::Handle::current();
    // construct the runtime metrics monitor
    let runtime_monitor = tokio_metrics::RuntimeMonitor::new(&handle);

    // print runtime metrics every 500ms
    {
        tokio::spawn(async move {
            for interval in runtime_monitor.intervals() {
                // pretty-print the metric interval
                println!("{:?}", interval);
                // wait 500ms
                tokio::time::sleep(Duration::from_millis(500)).await;
            }
        });
    }

    // await some tasks
    tokio::join![
        do_work(),
        do_work(),
        do_work(),
    ];

    Ok(())
}

async fn do_work() {
    for _ in 0..25 {
        tokio::task::yield_now().await;
        tokio::time::sleep(Duration::from_millis(100)).await;
    }
}

Monitoring and publishing runtime metrics (unstable)

If the metrics-rs-integration feature is additionally enabled, this crate allows publishing runtime metrics externally via metrics-rs exporters.

For example, you can use metrics_exporter_prometheus to make metrics visible to Prometheus. You can see the metrics_exporter_prometheus and metrics-rs docs for guidance on configuring exporters.

The published metrics are the same as the fields of RuntimeMetrics, but with a “tokio_” prefix added, for example tokio_workers_count.

This example exports Prometheus metrics by listening on a local Unix socket called prometheus.sock, which you can access for debugging by curl --unix-socket prometheus.sock localhost.

use std::time::Duration;

#[tokio::main]
async fn main() {
    metrics_exporter_prometheus::PrometheusBuilder::new()
        .with_http_uds_listener("prometheus.sock")
        .install()
        .unwrap();
    tokio::task::spawn(
        tokio_metrics::RuntimeMetricsReporterBuilder::default()
            // the default metric sampling interval is 30 seconds, which is
            // too long for quick tests, so have it be 1 second.
            .with_interval(std::time::Duration::from_secs(1))
            .describe_and_run(),
    );
    // Run some code
    tokio::task::spawn(async move {
        for _ in 0..1000 {
            tokio::time::sleep(Duration::from_millis(10)).await;
        }
    })
    .await
    .unwrap();
}

Structs

Instrumented

An async task that has been instrumented with TaskMonitor::instrument.

RuntimeIntervalstokio_unstable and rt

Iterator returned by RuntimeMonitor::intervals.

RuntimeMetricstokio_unstable and rt

Key runtime metrics.

RuntimeMetricsReportertokio_unstable and rt and metrics-rs-integration

Collects metrics from a Tokio runtime and uploads them to metrics_rs.

RuntimeMetricsReporterBuildertokio_unstable and rt and metrics-rs-integration

A builder for the a RuntimeMetricsReporter that wraps the RuntimeMonitor, periodically reporting RuntimeMetrics to any configured metrics-rs recorder.

RuntimeMonitortokio_unstable and rt

Monitors key metrics of the tokio runtime.

TaskMetrics

Key metrics of instrumented tasks.

TaskMonitor

Monitors key metrics of instrumented tasks.