Struct RuntimeMetrics

pub struct RuntimeMetrics { /* private fields */ }

Available on crate feature rt only.

Handle to the runtime’s metrics.

This handle is internally reference-counted and can be freely cloned. A RuntimeMetrics handle is obtained using the Runtime::metrics method.

Implementations

impl RuntimeMetrics

pub fn num_workers(&self) -> usize

Returns the number of worker threads used by the runtime.

The number of workers is set by configuring worker_threads on runtime::Builder. When using the current_thread runtime, the return value is always 1.

Examples

use tokio::runtime::Handle;

#[tokio::main]
async fn main() {
    let metrics = Handle::current().metrics();

    let n = metrics.num_workers();
    println!("Runtime is using {} workers", n);
}

pub fn num_alive_tasks(&self) -> usize

Returns the current number of alive tasks in the runtime.

This counter increases when a task is spawned and decreases when a task exits.

Examples

use tokio::runtime::Handle;

#[tokio::main]
async fn main() {
   let metrics = Handle::current().metrics();

    let n = metrics.num_alive_tasks();
    println!("Runtime has {} alive tasks", n);
}

pub fn global_queue_depth(&self) -> usize

Returns the number of tasks currently scheduled in the runtime’s global queue.

Tasks that are spawned or notified from a non-runtime thread are scheduled using the runtime’s global queue. This metric returns the current number of tasks pending in the global queue. As such, the returned value may increase or decrease as new tasks are scheduled and processed.

Examples

use tokio::runtime::Handle;

#[tokio::main]
async fn main() {
    let metrics = Handle::current().metrics();

    let n = metrics.global_queue_depth();
    println!("{} tasks currently pending in the runtime's global queue", n);
}

pub fn num_blocking_threads(&self) -> usize

Available on tokio_unstable only.

Returns the number of additional threads spawned by the runtime.

The number of workers is set by configuring max_blocking_threads on runtime::Builder.

Examples

use tokio::runtime::Handle;

#[tokio::main]
async fn main() {
    let _ = tokio::task::spawn_blocking(move || {
        // Stand-in for compute-heavy work or using synchronous APIs
        1 + 1
    }).await;
    let metrics = Handle::current().metrics();

    let n = metrics.num_blocking_threads();
    println!("Runtime has created {} threads", n);
}

pub fn active_tasks_count(&self) -> usize

👎Deprecated: Renamed to num_alive_tasks

Available on tokio_unstable only.

Renamed to RuntimeMetrics::num_alive_tasks

pub fn num_idle_blocking_threads(&self) -> usize

Available on tokio_unstable only.

Returns the number of idle threads, which have spawned by the runtime for spawn_blocking calls.

Examples

use tokio::runtime::Handle;

#[tokio::main]
async fn main() {
    let _ = tokio::task::spawn_blocking(move || {
        // Stand-in for compute-heavy work or using synchronous APIs
        1 + 1
    }).await;
    let metrics = Handle::current().metrics();

    let n = metrics.num_idle_blocking_threads();
    println!("Runtime has {} idle blocking thread pool threads", n);
}

pub fn worker_thread_id(&self, worker: usize) -> Option<ThreadId>

Available on tokio_unstable only.

Returns the thread id of the given worker thread.

The returned value is None if the worker thread has not yet finished starting up.

If additional information about the thread, such as its native id, are required, those can be collected in on_thread_start and correlated using the thread id.

Arguments

worker is the index of the worker being queried. The given value must be between 0 and num_workers(). The index uniquely identifies a single worker and will continue to identify the worker throughout the lifetime of the runtime instance.

Panics

The method panics when worker represents an invalid worker, i.e. is greater than or equal to num_workers().

Examples

use tokio::runtime::Handle;

#[tokio::main]
async fn main() {
    let metrics = Handle::current().metrics();

    let id = metrics.worker_thread_id(0);
    println!("worker 0 has id {:?}", id);
}

pub fn spawned_tasks_count(&self) -> u64

Available on target_has_atomic="64" only.

Returns the number of tasks spawned in this runtime since it was created.

This count starts at zero when the runtime is created and increases by one each time a task is spawned.

The counter is monotonically increasing. It is never decremented or reset to zero.

Examples

use tokio::runtime::Handle;

#[tokio::main]
async fn main() {
   let metrics = Handle::current().metrics();

    let n = metrics.spawned_tasks_count();
    println!("Runtime has had {} tasks spawned", n);
}

pub fn remote_schedule_count(&self) -> u64

Available on target_has_atomic="64" only.

Returns the number of tasks scheduled from outside of the runtime.

The remote schedule count starts at zero when the runtime is created and increases by one each time a task is woken from outside of the runtime. This usually means that a task is spawned or notified from a non-runtime thread and must be queued using the Runtime’s injection queue, which tends to be slower.

The counter is monotonically increasing. It is never decremented or reset to zero.

Examples

use tokio::runtime::Handle;

#[tokio::main]
async fn main() {
    let metrics = Handle::current().metrics();

    let n = metrics.remote_schedule_count();
    println!("{} tasks were scheduled from outside the runtime", n);
}

pub fn budget_forced_yield_count(&self) -> u64

Available on target_has_atomic="64" only.

Returns the number of times that tasks have been forced to yield back to the scheduler after exhausting their task budgets.

This count starts at zero when the runtime is created and increases by one each time a task yields due to exhausting its budget.

The counter is monotonically increasing. It is never decremented or reset to zero.

pub fn worker_park_count(&self, worker: usize) -> u64

Available on target_has_atomic="64" only.

Returns the total number of times the given worker thread has parked.

The worker park count starts at zero when the runtime is created and increases by one each time the worker parks the thread waiting for new inbound events to process. This usually means the worker has processed all pending work and is currently idle.

The counter is monotonically increasing. It is never decremented or reset to zero.

Arguments

worker is the index of the worker being queried. The given value must be between 0 and num_workers(). The index uniquely identifies a single worker and will continue to identify the worker throughout the lifetime of the runtime instance.

Panics

The method panics when worker represents an invalid worker, i.e. is greater than or equal to num_workers().

Examples

use tokio::runtime::Handle;

#[tokio::main]
async fn main() {
    let metrics = Handle::current().metrics();

    let n = metrics.worker_park_count(0);
    println!("worker 0 parked {} times", n);
}

pub fn worker_park_unpark_count(&self, worker: usize) -> u64

Available on target_has_atomic="64" only.

Returns the total number of times the given worker thread has parked and unparked.

The worker park/unpark count starts at zero when the runtime is created and increases by one each time the worker parks the thread waiting for new inbound events to process. This usually means the worker has processed all pending work and is currently idle. When new work becomes available, the worker is unparked and the park/unpark count is again increased by one.

An odd count means that the worker is currently parked. An even count means that the worker is currently active.

The counter is monotonically increasing. It is never decremented or reset to zero.

Arguments

worker is the index of the worker being queried. The given value must be between 0 and num_workers(). The index uniquely identifies a single worker and will continue to identify the worker throughout the lifetime of the runtime instance.

Panics

The method panics when worker represents an invalid worker, i.e. is greater than or equal to num_workers().

Examples

use tokio::runtime::Handle;

#[tokio::main]
async fn main() {
    let metrics = Handle::current().metrics();
    let n = metrics.worker_park_unpark_count(0);

    println!("worker 0 parked and unparked {} times", n);

    if n % 2 == 0 {
        println!("worker 0 is active");
    } else {
        println!("worker 0 is parked");
    }
}

pub fn worker_noop_count(&self, worker: usize) -> u64

Available on target_has_atomic="64" only.

Returns the number of times the given worker thread unparked but performed no work before parking again.

The worker no-op count starts at zero when the runtime is created and increases by one each time the worker unparks the thread but finds no new work and goes back to sleep. This indicates a false-positive wake up.

The counter is monotonically increasing. It is never decremented or reset to zero.

Arguments

worker is the index of the worker being queried. The given value must be between 0 and num_workers(). The index uniquely identifies a single worker and will continue to identify the worker throughout the lifetime of the runtime instance.

Panics

The method panics when worker represents an invalid worker, i.e. is greater than or equal to num_workers().

Examples

use tokio::runtime::Handle;

#[tokio::main]
async fn main() {
    let metrics = Handle::current().metrics();

    let n = metrics.worker_noop_count(0);
    println!("worker 0 had {} no-op unparks", n);
}

pub fn worker_steal_count(&self, worker: usize) -> u64

Available on target_has_atomic="64" only.

Returns the number of tasks the given worker thread stole from another worker thread.

This metric only applies to the multi-threaded runtime and will always return 0 when using the current thread runtime.

The worker steal count starts at zero when the runtime is created and increases by N each time the worker has processed its scheduled queue and successfully steals N more pending tasks from another worker.

The counter is monotonically increasing. It is never decremented or reset to zero.

Arguments

worker is the index of the worker being queried. The given value must be between 0 and num_workers(). The index uniquely identifies a single worker and will continue to identify the worker throughout the lifetime of the runtime instance.

Panics

The method panics when worker represents an invalid worker, i.e. is greater than or equal to num_workers().

Examples

use tokio::runtime::Handle;

#[tokio::main]
async fn main() {
    let metrics = Handle::current().metrics();

    let n = metrics.worker_steal_count(0);
    println!("worker 0 has stolen {} tasks", n);
}

pub fn worker_steal_operations(&self, worker: usize) -> u64

Available on target_has_atomic="64" only.

Returns the number of times the given worker thread stole tasks from another worker thread.

This metric only applies to the multi-threaded runtime and will always return 0 when using the current thread runtime.

The worker steal count starts at zero when the runtime is created and increases by one each time the worker has processed its scheduled queue and successfully steals more pending tasks from another worker.

The counter is monotonically increasing. It is never decremented or reset to zero.

Arguments

worker is the index of the worker being queried. The given value must be between 0 and num_workers(). The index uniquely identifies a single worker and will continue to identify the worker throughout the lifetime of the runtime instance.

Panics

The method panics when worker represents an invalid worker, i.e. is greater than or equal to num_workers().

Examples

use tokio::runtime::Handle;

#[tokio::main]
async fn main() {
    let metrics = Handle::current().metrics();

    let n = metrics.worker_steal_operations(0);
    println!("worker 0 has stolen tasks {} times", n);
}

pub fn worker_poll_count(&self, worker: usize) -> u64

Available on target_has_atomic="64" only.

Returns the number of tasks the given worker thread has polled.

The worker poll count starts at zero when the runtime is created and increases by one each time the worker polls a scheduled task.

The counter is monotonically increasing. It is never decremented or reset to zero.

Arguments

worker is the index of the worker being queried. The given value must be between 0 and num_workers(). The index uniquely identifies a single worker and will continue to identify the worker throughout the lifetime of the runtime instance.

Panics

The method panics when worker represents an invalid worker, i.e. is greater than or equal to num_workers().

Examples

use tokio::runtime::Handle;

#[tokio::main]
async fn main() {
    let metrics = Handle::current().metrics();

    let n = metrics.worker_poll_count(0);
    println!("worker 0 has polled {} tasks", n);
}

pub fn worker_total_busy_duration(&self, worker: usize) -> Duration

Available on target_has_atomic="64" only.

Returns the amount of time the given worker thread has been busy.

The worker busy duration starts at zero when the runtime is created and increases whenever the worker is spending time processing work. Using this value can indicate the load of the given worker. If a lot of time is spent busy, then the worker is under load and will check for inbound events less often.

The timer is monotonically increasing. It is never decremented or reset to zero.

Arguments

worker is the index of the worker being queried. The given value must be between 0 and num_workers(). The index uniquely identifies a single worker and will continue to identify the worker throughout the lifetime of the runtime instance.

Panics

The method panics when worker represents an invalid worker, i.e. is greater than or equal to num_workers().

Examples

use tokio::runtime::Handle;

#[tokio::main]
async fn main() {
    let metrics = Handle::current().metrics();

    let n = metrics.worker_total_busy_duration(0);
    println!("worker 0 was busy for a total of {:?}", n);
}

pub fn worker_local_schedule_count(&self, worker: usize) -> u64

Available on target_has_atomic="64" only.

Returns the number of tasks scheduled from within the runtime on the given worker’s local queue.

The local schedule count starts at zero when the runtime is created and increases by one each time a task is woken from inside of the runtime on the given worker. This usually means that a task is spawned or notified from within a runtime thread and will be queued on the worker-local queue.

The counter is monotonically increasing. It is never decremented or reset to zero.

Arguments

worker is the index of the worker being queried. The given value must be between 0 and num_workers(). The index uniquely identifies a single worker and will continue to identify the worker throughout the lifetime of the runtime instance.

Panics

The method panics when worker represents an invalid worker, i.e. is greater than or equal to num_workers().

Examples

use tokio::runtime::Handle;

#[tokio::main]
async fn main() {
    let metrics = Handle::current().metrics();

    let n = metrics.worker_local_schedule_count(0);
    println!("{} tasks were scheduled on the worker's local queue", n);
}

pub fn worker_overflow_count(&self, worker: usize) -> u64

Available on target_has_atomic="64" only.

Returns the number of times the given worker thread saturated its local queue.

This metric only applies to the multi-threaded scheduler.

The worker overflow count starts at zero when the runtime is created and increases by one each time the worker attempts to schedule a task locally, but its local queue is full. When this happens, half of the local queue is moved to the injection queue.

The counter is monotonically increasing. It is never decremented or reset to zero.

Arguments

worker is the index of the worker being queried. The given value must be between 0 and num_workers(). The index uniquely identifies a single worker and will continue to identify the worker throughout the lifetime of the runtime instance.

Panics

The method panics when worker represents an invalid worker, i.e. is greater than or equal to num_workers().

Examples

use tokio::runtime::Handle;

#[tokio::main]
async fn main() {
    let metrics = Handle::current().metrics();

    let n = metrics.worker_overflow_count(0);
    println!("worker 0 has overflowed its queue {} times", n);
}

pub fn worker_local_queue_depth(&self, worker: usize) -> usize

Available on tokio_unstable only.

Returns the number of tasks currently scheduled in the given worker’s local queue.

Tasks that are spawned or notified from within a runtime thread are scheduled using that worker’s local queue. This metric returns the current number of tasks pending in the worker’s local queue. As such, the returned value may increase or decrease as new tasks are scheduled and processed.

Arguments

worker is the index of the worker being queried. The given value must be between 0 and num_workers(). The index uniquely identifies a single worker and will continue to identify the worker throughout the lifetime of the runtime instance.

Panics

The method panics when worker represents an invalid worker, i.e. is greater than or equal to num_workers().

Examples

use tokio::runtime::Handle;

#[tokio::main]
async fn main() {
    let metrics = Handle::current().metrics();

    let n = metrics.worker_local_queue_depth(0);
    println!("{} tasks currently pending in worker 0's local queue", n);
}

pub fn poll_time_histogram_enabled(&self) -> bool

Available on tokio_unstable only.

Returns true if the runtime is tracking the distribution of task poll times.

Task poll times are not instrumented by default as doing so requires calling Instant::now() twice per task poll. The feature is enabled by calling enable_metrics_poll_time_histogram() when building the runtime.

Examples

use tokio::runtime::{self, Handle};

fn main() {
    runtime::Builder::new_current_thread()
        .enable_metrics_poll_time_histogram()
        .build()
        .unwrap()
        .block_on(async {
            let metrics = Handle::current().metrics();
            let enabled = metrics.poll_time_histogram_enabled();

            println!("Tracking task poll time distribution: {:?}", enabled);
        });
}

pub fn poll_time_histogram_num_buckets(&self) -> usize

Available on tokio_unstable only.

Returns the number of histogram buckets tracking the distribution of task poll times.

This value is configured by calling metrics_poll_time_histogram_configuration() when building the runtime.

Examples

use tokio::runtime::{self, Handle};

fn main() {
    runtime::Builder::new_current_thread()
        .enable_metrics_poll_time_histogram()
        .build()
        .unwrap()
        .block_on(async {
            let metrics = Handle::current().metrics();
            let buckets = metrics.poll_time_histogram_num_buckets();

            println!("Histogram buckets: {:?}", buckets);
        });
}

pub fn poll_time_histogram_bucket_range(&self, bucket: usize) -> Range<Duration>

Available on tokio_unstable only.

Returns the range of task poll times tracked by the given bucket.

This value is configured by calling metrics_poll_time_histogram_configuration() when building the runtime.

Panics

The method panics if bucket represents an invalid bucket index, i.e. is greater than or equal to poll_time_histogram_num_buckets().

Examples

use tokio::runtime::{self, Handle};

fn main() {
    runtime::Builder::new_current_thread()
        .enable_metrics_poll_time_histogram()
        .build()
        .unwrap()
        .block_on(async {
            let metrics = Handle::current().metrics();
            let buckets = metrics.poll_time_histogram_num_buckets();

            for i in 0..buckets {
                let range = metrics.poll_time_histogram_bucket_range(i);
                println!("Histogram bucket {} range: {:?}", i, range);
            }
        });
}

pub fn poll_time_histogram_bucket_count( &self, worker: usize, bucket: usize, ) -> u64

Available on target_has_atomic="64" only.

Returns the number of times the given worker polled tasks with a poll duration within the given bucket’s range.

Each worker maintains its own histogram and the counts for each bucket starts at zero when the runtime is created. Each time the worker polls a task, it tracks the duration the task poll time took and increments the associated bucket by 1.

Each bucket is a monotonically increasing counter. It is never decremented or reset to zero.

Arguments

worker is the index of the worker being queried. The given value must be between 0 and num_workers(). The index uniquely identifies a single worker and will continue to identify the worker throughout the lifetime of the runtime instance.

bucket is the index of the bucket being queried. The bucket is scoped to the worker. The range represented by the bucket can be queried by calling poll_time_histogram_bucket_range(). Each worker maintains identical bucket ranges.

Panics

The method panics when worker represents an invalid worker, i.e. is greater than or equal to num_workers() or if bucket represents an invalid bucket.

Examples

use tokio::runtime::{self, Handle};

fn main() {
    runtime::Builder::new_current_thread()
        .enable_metrics_poll_time_histogram()
        .build()
        .unwrap()
        .block_on(async {
            let metrics = Handle::current().metrics();
            let buckets = metrics.poll_time_histogram_num_buckets();

            for worker in 0..metrics.num_workers() {
                for i in 0..buckets {
                    let count = metrics.poll_time_histogram_bucket_count(worker, i);
                    println!("Poll count {}", count);
                }
            }
        });
}

pub fn worker_mean_poll_time(&self, worker: usize) -> Duration

Available on target_has_atomic="64" only.

Returns the mean duration of task polls, in nanoseconds.

This is an exponentially weighted moving average. Currently, this metric is only provided by the multi-threaded runtime.

Arguments

worker is the index of the worker being queried. The given value must be between 0 and num_workers(). The index uniquely identifies a single worker and will continue to identify the worker throughout the lifetime of the runtime instance.

Panics

The method panics when worker represents an invalid worker, i.e. is greater than or equal to num_workers().

Examples

use tokio::runtime::Handle;

#[tokio::main]
async fn main() {
    let metrics = Handle::current().metrics();

    let n = metrics.worker_mean_poll_time(0);
    println!("worker 0 has a mean poll time of {:?}", n);
}

pub fn blocking_queue_depth(&self) -> usize

Available on tokio_unstable only.

Returns the number of tasks currently scheduled in the blocking thread pool, spawned using spawn_blocking.

This metric returns the current number of tasks pending in blocking thread pool. As such, the returned value may increase or decrease as new tasks are scheduled and processed.

Examples

use tokio::runtime::Handle;

#[tokio::main]
async fn main() {
    let metrics = Handle::current().metrics();

    let n = metrics.blocking_queue_depth();
    println!("{} tasks currently pending in the blocking thread pool", n);
}

pub fn io_driver_fd_registered_count(&self) -> u64

Available on target_has_atomic="64" only.

Returns the number of file descriptors that have been registered with the runtime’s I/O driver.

Examples

use tokio::runtime::Handle;

#[tokio::main]
async fn main() {
    let metrics = Handle::current().metrics();

    let registered_fds = metrics.io_driver_fd_registered_count();
    println!("{} fds have been registered with the runtime's I/O driver.", registered_fds);

    let deregistered_fds = metrics.io_driver_fd_deregistered_count();

    let current_fd_count = registered_fds - deregistered_fds;
    println!("{} fds are currently registered by the runtime's I/O driver.", current_fd_count);
}

pub fn io_driver_fd_deregistered_count(&self) -> u64

Available on target_has_atomic="64" only.

Returns the number of file descriptors that have been deregistered by the runtime’s I/O driver.

Examples

use tokio::runtime::Handle;

#[tokio::main]
async fn main() {
    let metrics = Handle::current().metrics();

    let n = metrics.io_driver_fd_deregistered_count();
    println!("{} fds have been deregistered by the runtime's I/O driver.", n);
}

pub fn io_driver_ready_count(&self) -> u64

Available on target_has_atomic="64" only.

Returns the number of ready events processed by the runtime’s I/O driver.

Examples

use tokio::runtime::Handle;

#[tokio::main]
async fn main() {
    let metrics = Handle::current().metrics();

    let n = metrics.io_driver_ready_count();
    println!("{} ready events processed by the runtime's I/O driver.", n);
}

Trait Implementations

impl Clone for RuntimeMetrics

fn clone(&self) -> RuntimeMetrics

Returns a copy of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl Debug for RuntimeMetrics

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

Formats the value using the given formatter.