Struct Event 

pub struct Event<P = Pull>
where
    P: PublishModel,
{ /* private fields */ }

Allows you to observe the occurrences of an event in your code.

The typical pattern is to observe events via thread-local static variables.

Publishing models

The ultimate goal of the metrics collected by an Event is to end up in a Report. There are two models by which this can happen:

• Pull model - the reporting system queries each event in the process for its latest data set when generating a report. This is the default and requires no action from you.
• Push model - data from an event only flows to a thread-local MetricsPusher, which publishes the data into the reporting system on demand. This requires you to periodically trigger the publishing via MetricsPusher::push().

The push model has lower overhead but requires action from you to ensure that data is published. You may consider using it under controlled conditions, such as when you are certain that every thread that will be reporting data will also call the pusher at some point.

The choice of publishing model can be made separately for each event.

Example (pull model)

use nm::Event;

thread_local! {
    static CONNECT_TIME_MS: Event = Event::builder()
        .name("net_http_connect_time_ms")
        .build();
}

pub fn http_connect() {
    CONNECT_TIME_MS.with(|e| {
        e.observe_duration_millis(|| {
            do_http_connect();
        })
    });
}

Example (push model)

use nm::{Event, MetricsPusher, Push};

thread_local! {
    static HTTP_EVENTS_PUSHER: MetricsPusher = MetricsPusher::new();

    static CONNECT_TIME_MS: Event<Push> = Event::builder()
        .name("net_http_connect_time_ms")
        .pusher_local(&HTTP_EVENTS_PUSHER)
        .build();
}

pub fn http_connect() {
    CONNECT_TIME_MS.with(|e| {
        e.observe_duration_millis(|| {
            do_http_connect();
        })
    });
}

loop {
    http_connect();

    // Periodically push the data to the reporting system.
    if is_time_to_push() {
        HTTP_EVENTS_PUSHER.with(MetricsPusher::push);
    }
}

Thread safety

This type is single-threaded. You would typically create instances in a thread_local! block, so each thread gets its own instance.

Implementations

impl Event<Pull>

pub fn builder() -> EventBuilder<Pull>

Creates a new event builder with the default builder configuration.

impl<P> Event<P>

where P: PublishModel,

pub fn observe_once(&self)

Observes an event that has no explicit magnitude.

By convention, this is represented as a magnitude of 1. We expose a separate method for this to make it clear that the magnitude has no inherent meaning.

pub fn observe(&self, magnitude: impl AsPrimitive<Magnitude>)

Observes an event with a specific magnitude.

pub fn observe_millis(&self, duration: Duration)

Observes an event with the magnitude being the indicated duration in milliseconds.

Only the whole number part of the duration is used - fractional milliseconds are ignored. Values outside the i64 range are not guaranteed to be correctly represented.

pub fn observe_duration_millis<F, R>(&self, f: F) -> R

where F: FnOnce() -> R,

Observes the duration of a function call, in milliseconds.

pub fn batch(&self, count: usize) -> ObservationBatch<'_, P>

Prepares to observe a batch of events with the same magnitude.

Example

use nm::Event;

thread_local! {
    static REQUESTS_PROCESSED: Event = Event::builder()
        .name("requests_processed")
        .build();
    static HTTP_RESPONSE_TIME_MS: Event = Event::builder()
        .name("http_response_time_ms")
        .build();
}

// Record 100 HTTP responses, each taking 50ms
HTTP_RESPONSE_TIME_MS.with(|event| {
    event.batch(100).observe(50);
});

// Record 50 simple count events
REQUESTS_PROCESSED.with(|event| {
    event.batch(50).observe_once();
});

Trait Implementations

impl<P> Debug for Event<P>

where P: PublishModel + Debug,

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

Formats the value using the given formatter.

impl<P> Observe for Event<P>

where P: PublishModel,

fn observe_once(&self)

Observes an event that has no explicit magnitude.

fn observe(&self, magnitude: impl AsPrimitive<Magnitude>)

Observes an event with a specific magnitude.

fn observe_millis(&self, duration: Duration)

Observes an event with the magnitude being the indicated duration in milliseconds.

fn observe_duration_millis<F, R>(&self, f: F) -> R

where F: FnOnce() -> R,

Observes the duration of a function call, in milliseconds.