Struct Sink

Source

pub struct Sink { /* private fields */ }

Expand description

Handle for sending metric samples.

Implementations§

Source §

impl Sink

Source

pub fn add_default_labels<L>(&mut self, labels: L)
where L: IntoLabels,

Adds default labels for this sink and any derived sinks.

Default labels are added to all metrics. If a metric is updated and requested and it has its own labels specified, the default labels will be appended to the existing labels.

Labels are passed on, with scope, to any scoped children or cloned sinks.

Source

pub fn scoped<'a, S: AsScoped<'a> + ?Sized>(&self, scope: &'a S) -> Sink

Creates a scoped clone of this Sink.

Scoping controls the resulting metric name for any metrics sent by this Sink. For example, you might have a metric called messages_sent.

With scoping, you could have independent versions of the same metric. This is useful for having the same “base” metric name but with broken down values.

Going further with the above example, if you had a server, and listened on multiple addresses, maybe you would have a scoped Sink per listener, and could end up with metrics that look like this:

listener.a.messages_sent
listener.b.messages_sent
listener.c.messages_sent
etc

Scopes are also inherited. If you create a scoped Sink from another Sink which is already scoped, the scopes will be merged together using a . as the string separator. This makes it easy to nest scopes. Cloning a scoped Sink, though, will inherit the same scope as the original.

Source

pub fn now(&self) -> u64

Gets the current time, in nanoseconds, from the internal high-speed clock.

Source

pub fn increment_counter<N>(&mut self, name: N, value: u64)
where N: Into<Key>,

Increment a value for a counter identified by the given name.

§Examples

let receiver = Receiver::builder().build().expect("failed to create receiver");
let mut sink = receiver.sink();
sink.increment_counter("messages_processed", 1);

Source

pub fn increment_counter_with_labels<N, L>( &mut self, name: N, value: u64, labels: L, )
where N: Into<ScopedString>, L: IntoLabels,

Increment a value for a counter identified by the given name and labels.

§Examples

let receiver = Receiver::builder().build().expect("failed to create receiver");
let mut sink = receiver.sink();
sink.increment_counter_with_labels("messages_processed", 1, &[("message_type", "mgmt")]);

Source

pub fn update_gauge<N>(&mut self, name: N, value: i64)
where N: Into<Key>,

Update a value for a gauge identified by the given name.

§Examples

let receiver = Receiver::builder().build().expect("failed to create receiver");
let mut sink = receiver.sink();
sink.update_gauge("current_offset", -131);

Source

pub fn update_gauge_with_labels<N, L>(&mut self, name: N, value: i64, labels: L)
where N: Into<ScopedString>, L: IntoLabels,

Update a value for a gauge identified by the given name and labels.

§Examples

let receiver = Receiver::builder().build().expect("failed to create receiver");
let mut sink = receiver.sink();
sink.update_gauge_with_labels("current_offset", -131, &[("source", "stratum-1")]);

Source

pub fn record_timing<N, V>(&mut self, name: N, start: V, end: V)
where N: Into<Key>, V: Delta,

Records the value for a timing histogram identified by the given name.

Both the start and end times must be supplied, but any values that implement Delta can be used which allows for raw values from quanta::Clock to be used, or measurements from Instant::now.

§Examples

let receiver = Receiver::builder().build().expect("failed to create receiver");
let mut sink = receiver.sink();
let start = sink.now();
thread::sleep(Duration::from_millis(10));
let end = sink.now();
sink.record_timing("sleep_time", start, end);

Source

pub fn record_timing_with_labels<N, L, V>( &mut self, name: N, start: V, end: V, labels: L, )
where N: Into<ScopedString>, L: IntoLabels, V: Delta,

Records the value for a timing histogram identified by the given name and labels.

Both the start and end times must be supplied, but any values that implement Delta can be used which allows for raw values from quanta::Clock to be used, or measurements from Instant::now.

§Examples

let receiver = Receiver::builder().build().expect("failed to create receiver");
let mut sink = receiver.sink();
let start = sink.now();
thread::sleep(Duration::from_millis(10));
let end = sink.now();
sink.record_timing_with_labels("sleep_time", start, end, &[("mode", "low_priority")]);

Source

pub fn record_value<N>(&mut self, name: N, value: u64)
where N: Into<Key>,

Records the value for a value histogram identified by the given name.

§Examples

let receiver = Receiver::builder().build().expect("failed to create receiver");
let mut sink = receiver.sink();
sink.record_value("rows_returned", 42);

Source

pub fn record_value_with_labels<N, L>(&mut self, name: N, value: u64, labels: L)
where N: Into<ScopedString>, L: IntoLabels,

Records the value for a value histogram identified by the given name and labels.

§Examples

let receiver = Receiver::builder().build().expect("failed to create receiver");
let mut sink = receiver.sink();
sink.record_value_with_labels("rows_returned", 42, &[("table", "posts")]);

Source

pub fn counter<N>(&mut self, name: N) -> Counter
where N: Into<Key>,

Creates a handle to the given counter.

This handle can be embedded into an existing type and used to directly update the underlying counter without requiring a Sink. This method can be called multiple times with the same name and the handle will point to the single underlying instance.

Counter is clonable. `

§Examples

let receiver = Receiver::builder().build().expect("failed to create receiver");
let mut sink = receiver.sink();
let counter = sink.counter("messages_processed");
counter.record(1);

// Alternate, simpler usage:
counter.increment();

Source

pub fn counter_with_labels<N, L>(&mut self, name: N, labels: L) -> Counter
where N: Into<ScopedString>, L: IntoLabels,

Creates a handle to the given counter, with labels attached.

This handle can be embedded into an existing type and used to directly update the underlying counter without requiring a Sink. This method can be called multiple times with the same name/labels and the handle will point to the single underlying instance.

Counter is clonable.

§Examples

let receiver = Receiver::builder().build().expect("failed to create receiver");
let mut sink = receiver.sink();
let counter = sink.counter_with_labels("messages_processed", &[("service", "secure")]);
counter.record(1);

// Alternate, simpler usage:
counter.increment();

Source

pub fn gauge<N>(&mut self, name: N) -> Gauge
where N: Into<Key>,

Creates a handle to the given gauge.

This handle can be embedded into an existing type and used to directly update the underlying gauge without requiring a Sink. This method can be called multiple times with the same name and the handle will point to the single underlying instance.

Gauge is clonable.

§Examples

let receiver = Receiver::builder().build().expect("failed to create receiver");
let mut sink = receiver.sink();
let gauge = sink.gauge("current_offset");
gauge.record(-131);

Source

pub fn gauge_with_labels<N, L>(&mut self, name: N, labels: L) -> Gauge
where N: Into<ScopedString>, L: IntoLabels,

Creates a handle to the given gauge, with labels attached.

This handle can be embedded into an existing type and used to directly update the underlying gauge without requiring a Sink. This method can be called multiple times with the same name/labels and the handle will point to the single underlying instance.

Gauge is clonable.

§Examples

let receiver = Receiver::builder().build().expect("failed to create receiver");
let mut sink = receiver.sink();
let gauge = sink.gauge_with_labels("current_offset", &[("source", "stratum-1")]);
gauge.record(-131);

Source

pub fn histogram<N>(&mut self, name: N) -> Histogram
where N: Into<Key>,

Creates a handle to the given histogram.

This handle can be embedded into an existing type and used to directly update the underlying histogram without requiring a Sink. This method can be called multiple times with the same name and the handle will point to the single underlying instance.

Histogram is clonable.

§Examples

let receiver = Receiver::builder().build().expect("failed to create receiver");
let mut sink = receiver.sink();
let histogram = sink.histogram("request_duration");

let start = sink.now();
thread::sleep(Duration::from_millis(10));
let end = sink.now();
histogram.record_timing(start, end);

// Alternatively, you can just push the raw value into a histogram:
let delta = end - start;
histogram.record_value(delta);

Source

pub fn histogram_with_labels<N, L>(&mut self, name: N, labels: L) -> Histogram
where N: Into<ScopedString>, L: IntoLabels,

Creates a handle to the given histogram, with labels attached.

This handle can be embedded into an existing type and used to directly update the underlying histogram without requiring a Sink. This method can be called multiple times with the same name and the handle will point to the single underlying instance.

Histogram is clonable.

§Examples

let receiver = Receiver::builder().build().expect("failed to create receiver");
let mut sink = receiver.sink();
let histogram = sink.histogram_with_labels("request_duration", &[("service", "secure")]);

let start = sink.now();
thread::sleep(Duration::from_millis(10));
let end = sink.now();
histogram.record_timing(start, end);

// Alternatively, you can just push the raw value into a histogram:
let delta = end - start;
histogram.record_value(delta);

Source

pub fn proxy<N, F>(&mut self, name: N, f: F)
where N: Into<Key>, F: Fn() -> Vec<(Key, Measurement)> + Send + Sync + 'static,

Creates a proxy metric.

Proxy metrics allow you to register a closure that, when a snapshot of the metric state is requested, will be called and have a chance to return multiple metrics that are added to the overall metric of actual metrics.

This can be useful for metrics which are expensive to constantly recalculate/poll, allowing you to avoid needing to calculate/push them them yourself, with all the boilerplate that comes with doing so periodically.

Individual metrics must provide their own key (name), which will be appended to the name given when registering the proxy. A proxy can be reregistered at any time by calling this function again with the same name.

§Examples

let receiver = Receiver::builder().build().expect("failed to create receiver");
let mut sink = receiver.sink();

// A proxy is now registered under the name "load_stats", which is prepended to all the
// metrics generated by the closure i.e. "load_stats.avg_1min".  These metrics are also
// still scoped normally based on the [`Sink`].
sink.proxy("load_stats", || {
    let mut values = Vec::new();
    values.push((Key::from_name("avg_1min"), Measurement::Gauge(19)));
    values.push((Key::from_name("avg_5min"), Measurement::Gauge(12)));
    values.push((Key::from_name("avg_10min"), Measurement::Gauge(10)));
    values
});

Source

pub fn proxy_with_labels<N, L, F>(&mut self, name: N, labels: L, f: F)
where N: Into<ScopedString>, L: IntoLabels, F: Fn() -> Vec<(Key, Measurement)> + Send + Sync + 'static,

Creates a proxy metric, with labels attached.

Proxy metrics allow you to register a closure that, when a snapshot of the metric state is requested, will be called and have a chance to return multiple metrics that are added to the overall metric of actual metrics.

This can be useful for metrics which are expensive to constantly recalculate/poll, allowing you to avoid needing to calculate/push them them yourself, with all the boilerplate that comes with doing so periodically.

Individual metrics must provide their own key (name), which will be appended to the name given when registering the proxy. A proxy can be reregistered at any time by calling this function again with the same name.

§Examples

let receiver = Receiver::builder().build().expect("failed to create receiver");
let mut sink = receiver.sink();

let system_name = "web03".to_string();

// A proxy is now registered under the name "load_stats", which is prepended to all the
// metrics generated by the closure i.e. "load_stats.avg_1min".  These metrics are also
// still scoped normally based on the [`Sink`].
sink.proxy_with_labels("load_stats", &[("system", system_name)], || {
    let mut values = Vec::new();
    values.push((Key::from_name("avg_1min"), Measurement::Gauge(19)));
    values.push((Key::from_name("avg_5min"), Measurement::Gauge(12)));
    values.push((Key::from_name("avg_10min"), Measurement::Gauge(10)));
    values
});