Struct cadence::MetricBuilder

pub struct MetricBuilder<'m, 'c, T>
where
    T: Metric + From<String>,
{ /* private fields */ }

Builder for adding tags to in-progress metrics.

This builder adds tags, key-value pairs or just values, to a metric that was previously constructed by a call to a method on StatsdClient. The tags are added to metrics and sent via the client when MetricBuilder::send() or MetricBuilder::try_send()is invoked. Any errors encountered constructing, validating, or sending the metrics will be propagated and returned when those methods are finally invoked.

Currently, only Datadog style tags are supported. For more information on the exact format used, see the Datadog docs.

Adding tags to a metric via this builder will typically result in one or more extra heap allocations.

NOTE: The only way to instantiate an instance of this builder is via methods in in the StatsdClient client.

Examples

.try_send()

An example of how the metric builder is used with a StatsdClient instance is given below.

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

let client = StatsdClient::from_sink("some.prefix", NopMetricSink);
let res = client.count_with_tags("some.key", 1)
   .with_tag("host", "app11.example.com")
   .with_tag("segment", "23")
   .with_tag_value("beta")
   .try_send();

assert_eq!(
    concat!(
        "some.prefix.some.key:1|c|#",
        "host:app11.example.com,",
        "segment:23,",
        "beta"
    ),
    res.unwrap().as_metric_str()
);

In this example, two key-value tags and one value tag are added to the metric before it is finally sent to the Statsd server.

.send()

An example of how the metric builder is used with a StatsdClient instance when using the “quiet” method is given below.

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

let client = StatsdClient::builder("some.prefix", NopMetricSink)
    .with_error_handler(|e| eprintln!("metric error: {}", e))
    .build();
client.count_with_tags("some.key", 1)
   .with_tag("host", "app11.example.com")
   .with_tag("segment", "23")
   .with_tag_value("beta")
   .send();

Note that nothing is returned from the .send() method. Any errors encountered in this case will be passed to the error handler we registered.

Implementations

impl<'m, 'c, T> MetricBuilder<'m, 'c, T>

where T: Metric + From<String>,

pub fn with_tag(self, key: &'m str, value: &'m str) -> Self

Add a key-value tag to this metric.

Example

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

let client = StatsdClient::from_sink("some.prefix", NopMetricSink);
let res = client.count_with_tags("some.key", 1)
   .with_tag("user", "authenticated")
   .try_send();

assert_eq!(
   "some.prefix.some.key:1|c|#user:authenticated",
   res.unwrap().as_metric_str()
);

Examples found in repository

examples/value-packing.rs (line 31)

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 35)

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(self, value: &'m str) -> Self

Add a value tag to this metric.

Example

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

let client = StatsdClient::from_sink("some.prefix", NopMetricSink);
let res = client.count_with_tags("some.key", 4)
   .with_tag_value("beta-testing")
   .try_send();

assert_eq!(
   "some.prefix.some.key:4|c|#beta-testing",
   res.unwrap().as_metric_str()
);

pub fn try_send(self) -> MetricResult<T>

Send a metric using the client that created this builder.

Note that the builder is consumed by this method and thus .try_send() can only be called a single time per builder.

Example

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

let client = StatsdClient::from_sink("some.prefix", NopMetricSink);
let res = client.gauge_with_tags("some.key", 7)
   .with_tag("test-segment", "12345")
   .try_send();

assert_eq!(
   "some.prefix.some.key:7|g|#test-segment:12345",
   res.unwrap().as_metric_str()
);

Examples found in repository

examples/value-packing.rs (line 42)

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 46)

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 send(self)

Send a metric using the client that created this builder, discarding successful results and invoking a custom handler for error results.

By default, if no handler is given, a “no-op” handler is used that simply discards all errors. If this isn’t desired, a custom handler should be supplied when creating a new StatsdClient instance.

Note that the builder is consumed by this method and thus .send() can only be called a single time per builder.

Example

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

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

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

client.gauge_with_tags("some.key", 7)
   .with_tag("region", "us-west-1")
   .send();

Examples found in repository

examples/value-packing.rs (line 33)

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 37)

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);
}

Trait Implementations

impl<'m, 'c, T> Debug for MetricBuilder<'m, 'c, T>

where T: Metric + From<String> + Debug,

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

Formats the value using the given formatter.