Struct EventBuilder

Source

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

Expand description

Creates instances of Event.

Required parameters:

name

Use Event::builder() to create a new instance of this builder.

See crate-level documentation for more details on how to create and use events.

Implementations§

Source §

impl EventBuilder
where P: PublishModel,

Source

pub fn name(self, name: impl Into<EventName>) -> Self

Sets the name of the event. This is a required property.

Recommended format: big_medium_small_units For example: net_http_connect_time_ns

§Example

use nm::Event;

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

Source

pub fn histogram(self, buckets: &'static [Magnitude]) -> Self

Sets the upper bounds (inclusive) of histogram buckets to use when creating a histogram of event magnitudes.

The default is to not create a histogram.

§Example

use nm::{Event, Magnitude};

const RESPONSE_TIME_BUCKETS_MS: &[Magnitude] = &[1, 10, 50, 100, 500, 1000];

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

§Panics

Panics if bucket magnitudes are not in ascending order.

Panics if one of the values is Magnitude::MAX. You do not need to specify this bucket yourself - it is automatically synthesized for all histograms to catch values that exceed the user-defined buckets.

Source §

impl EventBuilder<Pull>

Source

pub fn pusher(self, pusher: &MetricsPusher) -> EventBuilder<Push>

Configures the event to be published using the push model, whereby a pusher is used to explicitly publish data for reporting purposes.

Any data from such an event will only reach reports after MetricsPusher::push() is called on the referenced pusher.

This can provide lower overhead than the pull model, which is the default, at the cost of delaying data updates until the pusher is invoked. Note that if nothing ever calls the pusher on a thread, the data from that thread will never be published.

§Example

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

let pusher = MetricsPusher::new();
let push_event: Event<Push> = Event::builder()
    .name("push_example")
    .pusher(&pusher)
    .build();

Source

pub fn pusher_local( self, pusher: &'static LocalKey<MetricsPusher>, ) -> EventBuilder<Push>

Configures the event to be published using the push model, whereby a pusher is used to explicitly publish data for reporting purposes.

Any data from such an event will only reach reports after MetricsPusher::push() is called on the referenced pusher.

This can provide lower overhead than the pull model, which is the default, at the cost of delaying data updates until the pusher is invoked. Note that if nothing ever calls the pusher on a thread, the data from that thread will never be published.

§Example

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

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

    static PUSH_EVENT: Event<Push> = Event::builder()
        .name("push_local_example")
        .pusher_local(&PUSHER)
        .build();
}

Source