# Tokio metrics collector for Prometheus

[![tokio-metrics-collector on GitHub Action][action-image]][action]
[![codecov][codecov-image]][codecov]
[![tokio-metrics-collector on crates.io][cratesio-image]][cratesio]
[![tokio-metrics-collector on docs.rs][docsrs-image]][docsrs]

[action-image]: https://github.com/Hanaasagi/tokio-metrics-collector/actions/workflows/ci.yaml/badge.svg
[action]: https://github.com/Hanaasagi/tokio-metrics-collector/actions/workflows/ci.yaml
[codecov-image]: https://codecov.io/gh/Hanaasagi/tokio-metrics-collector/branch/master/graph/badge.svg?token=TP67FTFT1K
[codecov]: https://codecov.io/gh/Hanaasagi/tokio-metrics-collector
[cratesio-image]: https://img.shields.io/crates/v/tokio-metrics-collector.svg
[cratesio]: https://crates.io/crates/tokio-metrics-collector
[docsrs-image]: https://docs.rs/tokio-metrics-collector/badge.svg
[docsrs]: https://docs.rs/tokio-metrics-collector

Provides utilities for collecting Prometheus-compatible metrics from Tokio runtime and tasks.

```toml
[dependencies]
tokio-metrics-collector = { version = "0.2.3" }
```

Documentation:

- [API reference (docs.rs)](https://docs.rs/tokio-metrics-collector/)

## QuickStart

```Rust
use prometheus::Encoder;

#[tokio::main]
async fn main() {
    // register global runtime collector
    prometheus::default_registry()
        .register(Box::new(
            tokio_metrics_collector::default_runtime_collector(),
        ))
        .unwrap();

    // register global task collector
    let task_collector = tokio_metrics_collector::default_task_collector();
    prometheus::default_registry()
        .register(Box::new(task_collector))
        .unwrap();

    // construct a TaskMonitor
    let monitor = tokio_metrics_collector::TaskMonitor::new();
    // add this monitor to task collector with label 'simple_task'
    // NOTE: duplicate labels in multiple monitors cause incorrect data aggregation.
    // It is recommended to use unique labels for each monitor and
    // instrument multiple tasks by the `instrument` function.
    task_collector.add("simple_task", monitor.clone());

    // spawn a background task and instrument
    tokio::spawn(monitor.instrument(async {
        loop {
            // do something
            tokio::time::sleep(tokio::time::Duration::from_millis(500)).await;
        }
    }));

    // print metrics every tick
    for _ in 0..5 {
        tokio::time::sleep(tokio::time::Duration::from_secs(1)).await;

        let encoder = prometheus::TextEncoder::new();
        let mut buffer = Vec::new();
        encoder
            .encode(&prometheus::default_registry().gather(), &mut buffer)
            .unwrap();
        let data = String::from_utf8(buffer.clone()).unwrap();

        println!("{}", data);
    }
}
```

And a http server example, you can find in `examples/server.rs`.

## Runtime Metrics

This unstable functionality requires `tokio_unstable`, and the `rt` crate
feature. To enable `tokio_unstable`, the `--cfg` `tokio_unstable` must be passed
to `rustc` when compiling. You can do this by setting the `RUSTFLAGS`
environment variable before compiling your application; e.g.:

```sh
RUSTFLAGS="--cfg tokio_unstable" cargo build
```

Or, by creating the file `.cargo/config.toml` in the root directory of your crate.
If you're using a workspace, put this file in the root directory of your workspace instead.

```toml
[build]
rustflags = ["--cfg", "tokio_unstable"]
rustdocflags = ["--cfg", "tokio_unstable"]
```

- **[`workers_count`]** | type: Gauge  
  The number of worker threads used by the runtime.
- **[`total_park_count`]** | type: Counter  
  The number of times worker threads parked.
- **[`total_noop_count`]** | type: Counter  
  The number of times worker threads unparked but performed no work before parking again.
- **[`total_steal_count`]** | type: Counter  
  The number of tasks worker threads stole from another worker thread.
- **[`total_steal_operations`]** | type: Counter  
  The number of times worker threads stole tasks from another worker thread.
- **[`num_remote_schedules`]** | type: Counter  
  The number of tasks scheduled from outside of the runtime.
- **[`total_local_schedule_count`]** | type: Counter  
  The number of tasks scheduled from worker threads.
- **[`total_overflow_count`]** | type: Counter  
  The number of times worker threads saturated their local queues.
- **[`total_polls_count`]** | type: Counter  
  The number of tasks that have been polled across all worker threads.
- **[`total_busy_duration`]** | type: Counter  
  The amount of time worker threads were busy.
- **[`injection_queue_depth`]** | type: Gauge  
  The number of tasks currently scheduled in the runtime's injection queue.
- **[`total_local_queue_depth`]** | type: Gauge  
  The total number of tasks currently scheduled in workers' local queues.
- **[`elapsed`]** | type: Counter  
  Total amount of time elapsed since observing runtime metrics.
- **[`budget_forced_yield_count`]** | type: Counter  
  The number of times that a task was forced to yield because it exhausted its budget.
- **[`io_driver_ready_count`]** | type: Counter
  The number of ready events received from the I/O driver.

[`workers_count`]: https://docs.rs/tokio-metrics/0.2.*/tokio_metrics/struct.RuntimeMetrics.html#structfield.workers_count
[`total_park_count`]: https://docs.rs/tokio-metrics/0.2.*/tokio_metrics/struct.RuntimeMetrics.html#structfield.total_park_count
[`total_noop_count`]: https://docs.rs/tokio-metrics/0.2.*/tokio_metrics/struct.RuntimeMetrics.html#structfield.total_noop_count
[`total_steal_count`]: https://docs.rs/tokio-metrics/0.2.*/tokio_metrics/struct.RuntimeMetrics.html#structfield.total_steal_count
[`total_steal_operations`]: https://docs.rs/tokio-metrics/0.2.*/tokio_metrics/struct.RuntimeMetrics.html#structfield.total_steal_operations
[`num_remote_schedules`]: https://docs.rs/tokio-metrics/0.2.*/tokio_metrics/struct.RuntimeMetrics.html#structfield.num_remote_schedules
[`total_local_schedule_count`]: https://docs.rs/tokio-metrics/0.2.*/tokio_metrics/struct.RuntimeMetrics.html#structfield.total_local_schedule_count
[`total_overflow_count`]: https://docs.rs/tokio-metrics/0.2.*/tokio_metrics/struct.RuntimeMetrics.html#structfield.total_overflow_count
[`total_polls_count`]: https://docs.rs/tokio-metrics/0.2.*/tokio_metrics/struct.RuntimeMetrics.html#structfield.total_polls_count
[`total_busy_duration`]: https://docs.rs/tokio-metrics/0.2.*/tokio_metrics/struct.RuntimeMetrics.html#structfield.total_busy_duration
[`injection_queue_depth`]: https://docs.rs/tokio-metrics/0.2.*/tokio_metrics/struct.RuntimeMetrics.html#structfield.injection_queue_depth
[`total_local_queue_depth`]: https://docs.rs/tokio-metrics/0.2.*/tokio_metrics/struct.RuntimeMetrics.html#structfield.total_local_queue_depth
[`elapsed`]: https://docs.rs/tokio-metrics/0.2.*/tokio_metrics/struct.RuntimeMetrics.html#structfield.elapsed
[`mean_polls_per_park`]: https://docs.rs/tokio-metrics/0.2.*/tokio_metrics/struct.RuntimeMetrics.html#method.mean_polls_per_park
[`busy_ratio`]: https://docs.rs/tokio-metrics/0.2.*/tokio_metrics/struct.RuntimeMetrics.html#method.busy_ratio
[`budget_forced_yield_count`]: https://docs.rs/tokio-metrics/0.2.*/tokio_metrics/struct.RuntimeMetrics.html#structfield.budget_forced_yield_count
[`io_driver_ready_count`]: https://docs.rs/tokio-metrics/0.2.*/tokio_metrics/struct.RuntimeMetrics.html#structfield.io_driver_ready_count

## Task Metrics

- **[`instrumented_count`]** | type: Gauge  
  The number of tasks instrumented in the interval.
- **[`dropped_count`]** | type: Gauge
  The number of tasks dropped in the interval.
- **[`first_poll_count`]** | type: Gauge  
  The number of tasks polled for the first time in the interval.
- **[`total_first_poll_delay`]** | type: Counter
  The total duration elapsed between the instant tasks are instrumented, and the instant they are first polled.
- **[`total_idled_count`]** | type: Counter
  The total number of times that tasks idled, waiting to be awoken.
- **[`total_idle_duration`]** | type: Counter
  The total duration that tasks idled.
- **[`total_scheduled_count`]** | type: Counter
  The total number of times that tasks were awoken (and then, presumably, scheduled for execution).
- **[`total_scheduled_duration`]** | type: Counter
  The total duration that tasks spent waiting to be polled after awakening.
- **[`total_poll_count`]** | type: Counter
  The total number of times that tasks were polled.
- **[`total_poll_duration`]** | type: Counter
  The total duration elapsed during polls.
- **[`total_fast_poll_count`]** | type: Counter
  The total number of times that polling tasks completed swiftly.
- **[`total_fast_poll_duration`]** | type: Counter
  The total duration of fast polls.
- **[`total_slow_poll_count`]** | type: Counter
  The total number of times that polling tasks completed slowly.
- **[`total_slow_poll_duration`]** | type: Counter
  The total duration of slow polls.
- **[`total_short_delay_count`]** | type: Counter
  The total count of short scheduling delays.
- **[`total_short_delay_duration`]** | type: Counter
  The total duration of short scheduling delays.
- **[`total_long_delay_count`]** | type: Counter
  The total count of long scheduling delays.
- **[`total_long_delay_duration`]** | type: Counter
  The total duration of long scheduling delays.
- **[`tokio_task_total_first_poll_count`]** | type: Counter
  The total number of tasks polled for the first time.

[`instrumented_count`]: https://docs.rs/tokio-metrics/0.2.*/tokio_metrics/struct.TaskMetrics.html#structfield.instrumented_count
[`dropped_count`]: https://docs.rs/tokio-metrics/0.2.*/tokio_metrics/struct.TaskMetrics.html#structfield.dropped_count
[`first_poll_count`]: https://docs.rs/tokio-metrics/0.2.*/tokio_metrics/struct.TaskMetrics.html#structfield.first_poll_count
[`total_first_poll_delay`]: https://docs.rs/tokio-metrics/0.2.*/tokio_metrics/struct.TaskMetrics.html#structfield.total_first_poll_delay
[`total_idled_count`]: https://docs.rs/tokio-metrics/0.2.*/tokio_metrics/struct.TaskMetrics.html#structfield.total_idled_count
[`total_idle_duration`]: https://docs.rs/tokio-metrics/0.2.*/tokio_metrics/struct.TaskMetrics.html#structfield.total_idle_duration
[`total_scheduled_count`]: https://docs.rs/tokio-metrics/0.2.*/tokio_metrics/struct.TaskMetrics.html#structfield.total_scheduled_count
[`total_scheduled_duration`]: https://docs.rs/tokio-metrics/0.2.*/tokio_metrics/struct.TaskMetrics.html#structfield.total_scheduled_duration
[`total_poll_count`]: https://docs.rs/tokio-metrics/0.2.*/tokio_metrics/struct.TaskMetrics.html#structfield.total_poll_count
[`total_poll_duration`]: https://docs.rs/tokio-metrics/0.2.*/tokio_metrics/struct.TaskMetrics.html#structfield.total_poll_duration
[`total_fast_poll_count`]: https://docs.rs/tokio-metrics/0.2.*/tokio_metrics/struct.TaskMetrics.html#structfield.total_fast_poll_count
[`total_fast_poll_duration`]: https://docs.rs/tokio-metrics/0.2.*/tokio_metrics/struct.TaskMetrics.html#structfield.total_fast_poll_duration
[`total_slow_poll_count`]: https://docs.rs/tokio-metrics/0.2.*/tokio_metrics/struct.TaskMetrics.html#structfield.total_slow_poll_count
[`total_slow_poll_duration`]: https://docs.rs/tokio-metrics/0.2.*/tokio_metrics/struct.TaskMetrics.html#structfield.total_slow_poll_duration
[`total_short_delay_count`]: https://docs.rs/tokio-metrics/0.2.*/tokio_metrics/struct.TaskMetrics.html#structfield.total_short_delay_count
[`total_short_delay_duration`]: https://docs.rs/tokio-metrics/0.2.*/tokio_metrics/struct.TaskMetrics.html#structfield.total_short_delay_duration
[`total_long_delay_count`]: https://docs.rs/tokio-metrics/0.2.*/tokio_metrics/struct.TaskMetrics.html#structfield.total_long_delay_count
[`total_long_delay_duration`]: https://docs.rs/tokio-metrics/0.2.*/tokio_metrics/struct.TaskMetrics.html#structfield.total_long_delay_duration
[`long_delay_ratio`]: https://docs.rs/tokio-metrics/0.2.*/tokio_metrics/struct.TaskMetrics.html#method.long_delay_ratio

## License

tokio-metrics-collector is distributed under the terms of both the MIT license and the Apache License (Version 2.0).

See LICENSE-APACHE and LICENSE-MIT, and COPYRIGHT for details.