Struct TaskMetricsReporterBuilder 

pub struct TaskMetricsReporterBuilder { /* private fields */ }

Available on crate features rt and metrics-rs-integration only.

A builder for the TaskMetricsReporter that wraps the TaskMonitor, periodically reporting TaskMetrics to any configured metrics-rs recorder.

Published Metrics

The published metrics are the fields of TaskMetrics, but with the tokio_ prefix added, for example, tokio_instrumented_count. If you have multiple TaskMonitors then it is strongly recommended to give each TaskMonitor a unique metric name or dimension value.

Usage

To upload metrics via metrics-rs, you need to set up a reporter, which is actually what exports the metrics outside of the program. You must set up the reporter before you call describe_and_run.

You can find exporters within the metrics-rs docs. One such reporter is the metrics_exporter_prometheus reporter, which makes metrics visible through Prometheus.

You can use it for example to export 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, as follows:

use std::time::Duration;

use metrics::Key;

#[tokio::main]
async fn main() {
    metrics_exporter_prometheus::PrometheusBuilder::new()
        .with_http_uds_listener("prometheus.sock")
        .install()
        .unwrap();
    let monitor = tokio_metrics::TaskMonitor::new();
    tokio::task::spawn(
        tokio_metrics::TaskMetricsReporterBuilder::new(|name| {
            let name = name.replacen("tokio_", "my_task_", 1);
            Key::from_parts(name, &[("application", "my_app")])
        })
        // 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(monitor.clone()),
    );
    // Run some code
    tokio::task::spawn(monitor.instrument(async move {
        for _ in 0..1000 {
            tokio::time::sleep(Duration::from_millis(10)).await;
        }
    }))
    .await
    .unwrap();
}

Implementations

impl TaskMetricsReporterBuilder

pub fn new( transformer: impl FnMut(&'static str) -> Key + Send + 'static, ) -> Self

Creates a new TaskMetricsReporterBuilder with a custom “metrics transformer”. The custom transformer is used during build to transform the metric names into metric keys, for example to add dimensions. The string metric names used by this reporter all start with tokio_. The default transformer is just metrics::Key::from_static_name

For example, to attach a dimension named “application” with value “my_app”, and to replace tokio_ with my_task_

#[tokio::main]
async fn main() {
    metrics_exporter_prometheus::PrometheusBuilder::new()
        .with_http_uds_listener("prometheus.sock")
        .install()
        .unwrap();
    let monitor = tokio_metrics::TaskMonitor::new();
    tokio::task::spawn(
        tokio_metrics::TaskMetricsReporterBuilder::new(|name| {
            let name = name.replacen("tokio_", "my_task_", 1);
            Key::from_parts(name, &[("application", "my_app")])
        })
        .describe_and_run(monitor)
    );
}

pub fn with_interval(self, interval: Duration) -> Self

Set the metric sampling interval, default: 30 seconds.

Note that this is the interval on which metrics are sampled from the Tokio task and then set on the metrics-rs reporter. Uploading the metrics upstream is controlled by the reporter set up in the application, and is normally controlled by a different period.

For example, if metrics are exported via Prometheus, that normally operates at a pull-based fashion, and the actual collection period is controlled by the Prometheus server, which periodically polls the application’s Prometheus exporter to get the latest value of the metrics.

pub fn build_with_monitor(self, monitor: TaskMonitor) -> TaskMetricsReporter

Build the TaskMetricsReporter with a specific TaskMonitor. This function will capture the Counters and Gauges from the current metrics-rs reporter, so if you are using with_local_recorder, you should wrap this function and describe with it.

pub fn describe(self) -> Self

Call describe_counter etc. to describe the emitted metrics.

Describing metrics makes the reporter attach descriptions and units to them, which makes them easier to use. However, some reporters don’t support describing the same metric name more than once, so it is generally a good idea to only call this function once per metric reporter.

pub async fn describe_and_run(self, monitor: TaskMonitor)

Runs the reporter (within the returned future), describing the metrics beforehand.

Describing metrics makes the reporter attach descriptions and units to them, which makes them easier to use. However, some reporters don’t support describing the same metric name more than once. If you are emitting multiple metrics via a single reporter, try to call describe once and run for each task metrics reporter.

Working with a custom reporter

If you want to set a local metrics reporter, you shouldn’t be calling this method, but you should instead call .describe().build() within with_local_recorder and then call run (see the docs on build_with_monitor).

pub async fn run_without_describing(self, monitor: TaskMonitor)

Runs the reporter (within the returned future), not describing the metrics beforehand.

Working with a custom reporter

If you want to set a local metrics reporter, you shouldn’t be calling this method, but you should instead call .describe().build() within with_local_recorder and then call run (see the docs on build_with_monitor).

Trait Implementations

impl Debug for TaskMetricsReporterBuilder

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.