Struct cadence::StatsdClientBuilder

pub struct StatsdClientBuilder { /* private fields */ }

Builder for creating and customizing StatsdClient instances.

Instances of the builder should be created by calling the ::builder() method on the StatsClient struct.

Example

use cadence::prelude::*;
use cadence::{MetricError, StatsdClient, NopMetricSink};

fn my_error_handler(err: MetricError) {
    println!("Metric error! {}", err);
}

let client = StatsdClient::builder("prefix", NopMetricSink)
    .with_error_handler(my_error_handler)
    .with_tag("environment", "production")
    .with_tag_value("rust")
    .build();

client.count("something", 123);
client.count_with_tags("some.counter", 42)
    .with_tag("region", "us-east-2")
    .send();

Implementations

impl StatsdClientBuilder

pub fn with_error_handler<F>(self, errors: F) -> Self

where F: Fn(MetricError) + Sync + Send + RefUnwindSafe + 'static,

Set an error handler to use for metrics sent via MetricBuilder::send()

The error handler is only invoked when metrics are not able to be sent correctly. Either due to invalid input, I/O errors encountered when trying to send them via a MetricSink, or some other reason.

The error handler should consume the error without panicking. The error may be logged, printed to stderr, discarded, etc. - this is up to the implementation.

Examples found in repository

examples/value-packing.rs (line 23)

fn main() {
    fn my_error_handler(err: MetricError) {
        eprintln!("Error sending metrics: {}", err);
    }

    let client = StatsdClient::builder("my.prefix", NopMetricSink)
        .with_error_handler(my_error_handler)
        .build();

    // In this case we are sending a distribution metric with two tag key-value
    // pairs. If sending the metric fails, our error handler set above will
    // be invoked to do something with the metric error.
    client
        .distribution_with_tags("latency.milliseconds", vec![10, 20, 30, 40, 50])
        .with_tag("app", "search")
        .with_tag("region", "us-west-2")
        .send();

    // In this case we are sending the same distribution metrics with two tags.
    // The results of sending the metric (or failing to send it) are returned
    // to the caller to do something with.
    let res = client
        .distribution_with_tags("latency.milliseconds", vec![10, 20, 30, 40, 50])
        .with_tag("app", "search")
        .with_tag("region", "us-west-2")
        .try_send();

    println!("Result of metric send: {:?}", res);
}

examples/sending-tags.rs (line 26)

fn main() {
    fn my_error_handler(err: MetricError) {
        eprintln!("Error sending metrics: {}", err);
    }

    // Create a client with an error handler and default "region" tag
    let client = StatsdClient::builder("my.prefix", NopMetricSink)
        .with_error_handler(my_error_handler)
        .with_tag("region", "us-west-2")
        .build();

    // In this case we are sending a counter metric with two tag key-value
    // pairs. If sending the metric fails, our error handler set above will
    // be invoked to do something with the metric error.
    client
        .count_with_tags("requests.handled", 1)
        .with_tag("app", "search")
        .with_tag("user", "1234")
        .send();

    // In this case we are sending the same counter metrics with two tags.
    // The results of sending the metric (or failing to send it) are returned
    // to the caller to do something with.
    let res = client
        .count_with_tags("requests.handled", 1)
        .with_tag("app", "search")
        .with_tag("user", "1234")
        .try_send();

    println!("Result of metric send: {:?}", res);
}

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

where K: ToString, V: ToString,

Add a default tag with key and value to every metric published by the built StatsdClient.

Examples found in repository

examples/sending-tags.rs (line 27)

fn main() {
    fn my_error_handler(err: MetricError) {
        eprintln!("Error sending metrics: {}", err);
    }

    // Create a client with an error handler and default "region" tag
    let client = StatsdClient::builder("my.prefix", NopMetricSink)
        .with_error_handler(my_error_handler)
        .with_tag("region", "us-west-2")
        .build();

    // In this case we are sending a counter metric with two tag key-value
    // pairs. If sending the metric fails, our error handler set above will
    // be invoked to do something with the metric error.
    client
        .count_with_tags("requests.handled", 1)
        .with_tag("app", "search")
        .with_tag("user", "1234")
        .send();

    // In this case we are sending the same counter metrics with two tags.
    // The results of sending the metric (or failing to send it) are returned
    // to the caller to do something with.
    let res = client
        .count_with_tags("requests.handled", 1)
        .with_tag("app", "search")
        .with_tag("user", "1234")
        .try_send();

    println!("Result of metric send: {:?}", res);
}

pub fn with_tag_value<K>(self, value: K) -> Self

where K: ToString,

Add a default tag with only a value to every metric published by the built StatsdClient.

pub fn build(self) -> StatsdClient

Construct a new StatsdClient instance based on current settings.

Examples found in repository

examples/value-packing.rs (line 24)

fn main() {
    fn my_error_handler(err: MetricError) {
        eprintln!("Error sending metrics: {}", err);
    }

    let client = StatsdClient::builder("my.prefix", NopMetricSink)
        .with_error_handler(my_error_handler)
        .build();

    // In this case we are sending a distribution metric with two tag key-value
    // pairs. If sending the metric fails, our error handler set above will
    // be invoked to do something with the metric error.
    client
        .distribution_with_tags("latency.milliseconds", vec![10, 20, 30, 40, 50])
        .with_tag("app", "search")
        .with_tag("region", "us-west-2")
        .send();

    // In this case we are sending the same distribution metrics with two tags.
    // The results of sending the metric (or failing to send it) are returned
    // to the caller to do something with.
    let res = client
        .distribution_with_tags("latency.milliseconds", vec![10, 20, 30, 40, 50])
        .with_tag("app", "search")
        .with_tag("region", "us-west-2")
        .try_send();

    println!("Result of metric send: {:?}", res);
}

examples/sending-tags.rs (line 28)

fn main() {
    fn my_error_handler(err: MetricError) {
        eprintln!("Error sending metrics: {}", err);
    }

    // Create a client with an error handler and default "region" tag
    let client = StatsdClient::builder("my.prefix", NopMetricSink)
        .with_error_handler(my_error_handler)
        .with_tag("region", "us-west-2")
        .build();

    // In this case we are sending a counter metric with two tag key-value
    // pairs. If sending the metric fails, our error handler set above will
    // be invoked to do something with the metric error.
    client
        .count_with_tags("requests.handled", 1)
        .with_tag("app", "search")
        .with_tag("user", "1234")
        .send();

    // In this case we are sending the same counter metrics with two tags.
    // The results of sending the metric (or failing to send it) are returned
    // to the caller to do something with.
    let res = client
        .count_with_tags("requests.handled", 1)
        .with_tag("app", "search")
        .with_tag("user", "1234")
        .try_send();

    println!("Result of metric send: {:?}", res);
}