Struct StatsdBuilder

pub struct StatsdBuilder { /* private fields */ }

StatsdBuilder is responsible building and configuring a StatsdRecorder.

Implementations

impl StatsdBuilder

pub fn from<S: Into<String>>(host: S, port: u16) -> Self

Configures the StatsdBuilder with provided host and port number. A StatsdError is returned to the caller if the values supplied for host and/or port are invalid. You can further customize other variables like queue_size and buffer_size by calling appropriate with_* methods on the builder.

pub fn with_queue_size(self, queue_size: usize) -> Self

Configure queue size for this builder, the queue size is eventually passed down to the underlying StatsdClient to control how many elements should be allowed to buffer in a queue. The default value for the queue size is 5000, Statsd client will error out and drop the new elements being sent to it once it hits this capacity.

pub fn with_buffer_size(self, buffer_size: usize) -> Self

Buffer size controls how much should be buffered in StatsdClient’s memory before they are actually written out over the socket. This value is conservatively set to 256 bytes and should be adjusted according to the application needs.

pub fn with_client_udp_host<S: Into<String>>(self, client_udp_host: S) -> Self

Host address to which the local udp socket would be bound, this address defaults to 0.0.0.0. Be careful with using 127.0.0.1 as systems like kubernetes might blackhole all the traffic routed to that address.

pub fn histogram_is_distribution(self) -> Self

A hint for the metric emitter to determine how the histogram metrics should be emitted, all the histogram metrics will be sent as distribution when running in this mode unless specified otherwise via a label.

pub fn histogram_is_timer(self) -> Self

A hint for the metric emitter to determine how the histogram metrics should be emitted, all the histogram metrics will be sent as timer when running in this mode unless specified otherwise via a label.

pub fn with_default_tag<K, V>(self, key: K, value: V) -> Self

where K: ToString, V: ToString,

Add a default tag with key and value to all statsd metrics produced with this recorder.

pub fn with_sink<T>(self, sink: T) -> Self

where T: MetricSink + Sync + Send + RefUnwindSafe + 'static,

Use a custom MetricSink.

This method supersedes all other settings for metrics output, including the hostname and port specified in StatsdBuilder::from and values passed to the with_queue_size, with_buffer_size, and with_client_udp_host methods. The specified sink is used instead.

(When this method is not called, the builder creates a default sink using those settings, cadence::QueuingMetricSink, and cadence::UdpMetricSink.)

Examples

This code replaces the ordinary UDP sink with output to a Unix socket.

use metrics_exporter_statsd::StatsdBuilder;
use cadence::BufferedUnixMetricSink;
use std::os::unix::net::UnixDatagram;

let path = "/path/to/my/metrics/socket";
let socket = UnixDatagram::bind(path)?;
let sink = BufferedUnixMetricSink::from(path, socket);

let recorder = StatsdBuilder::from("", 0)
    .with_sink(sink)
    .build(Some("my_app"))?;
metrics::set_global_recorder(recorder);

pub fn build(self, prefix: Option<&str>) -> Result<StatsdRecorder, StatsdError>

This method is responsible building the StatsdRecorder. It configures the underlying metrics sink for the StatsdClient with the values provided e.g. queue_size, buffer_size etc.

All the metrics emitted from the recorder are prefixed with the prefix that’s provided here.

Examples

use metrics_exporter_statsd::StatsdBuilder;
let recorder = StatsdBuilder::from("localhost", 8125)
               .build(Some("prefix"))
               .expect("Could not create StatsdRecorder");

metrics::set_global_recorder(recorder);
metrics::counter!("counter.name").increment(10);

will emit a counter metric name as prefix.counter.name

Trait Implementations

impl Default for StatsdBuilder

fn default() -> Self

Returns the “default value” for a type.