Struct InstrumentedFuture

pub struct InstrumentedFuture<F: Future> { /* private fields */ }

An instrumented Future.

InstrumentedFuture provides a transparent observability layer for futures. An instrumented future is not created directly. Rather, an instrumented future is created from an existing future using IntoInstrumentedFuture::into_instrumented_future.

Most importantly, the increment_until_resolved method allows callers to increment a GuardedGauge, and then decrement the gauge once the future has resolved.

Examples

use prometheus_utils::IntoInstrumentedFuture;
use tokio::time::{sleep, Duration};

#[tokio::main]
async fn main() {
    let fut = sleep(Duration::from_millis(100));
    let instrumented = fut.into_instrumented_future();
    let _res = instrumented.await;
}

Implementations

impl<F: Future> InstrumentedFuture<F>

pub fn with_guard<GuardFn: FnOnce() -> Option<Box<dyn Any + Send>> + Send + 'static>( self, guard_fn: GuardFn, ) -> Self

Queue guard_fn to execute when the future is polled, retaining the returned value until the future completes.

Examples

use prometheus_utils::IntoInstrumentedFuture;
use tokio::time::{sleep, Duration};

/// An RAII guard that will be attached to the future.
struct FutureGuard;

impl Drop for FutureGuard {
    fn drop(&mut self) {
        // This code will be run when the future is ready.
        println!("100ms have elapsed!");
    }
}

/// An asynchronous function.
async fn do_work() {
    sleep(Duration::from_millis(100)).await;
}

#[tokio::main]
async fn main() {
    do_work()
        .into_instrumented_future()
        .with_guard(|| {
            // This code will be run once the future is polled.
            println!("future was polled!");
            Some(Box::new(FutureGuard))
        })
        .await;
}

pub fn with_count<P: Atomic + 'static>( self, counter: &'static GenericCounter<P>, ) -> Self

Increment a Prometheus counter immediately.

pub fn with_count_labeled<C, L>(self, counter: &'static C, labels: L) -> Self

where C: Deref<Target = IntCounterWithLabels<L>> + Sync, L: Labels + Sync + Send + 'static,

Increment a labeled Prometheus counter when the future is polled.

pub fn with_count_gauge<G, T, P>(self, gauge: &'static G) -> Self

where G: Deref<Target = T> + Sync, T: GuardedGauge<P> + 'static, P: Atomic + 'static,

Increment a Prometheus gauge until this future has resolved.

When called, this method will immediately increment the given gauge using the GuardedGauge::gaurded_inc trait method. This gauge will then be decremented once this future’s Future::poll implementation returns a Poll::Ready value.

See the GenericGaugeGuard documentation for more information about RAII guards for Prometheus metrics.

Trait Implementations

impl<F: Future> Future for InstrumentedFuture<F>

type Output = <F as Future>::Output

An instrumented future returns the same type as its inner future.

fn poll(self: Pin<&mut Self>, cx: &mut Context<'_>) -> Poll<Self::Output>

Polls the inner future.

If the inner future’s [Future::poll][fut-poll] implementation returns a [Poll::Ready][poll-ready] value, Prometheus gauges will be decremented accordingly.

impl<'pin, F: Future> Unpin for InstrumentedFuture<F>

where PinnedFieldsOf<__InstrumentedFuture<'pin, F>>: Unpin,