Struct cadence::MetricBuilder
source · [−]Expand description
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
sourceimpl<'m, 'c, T> MetricBuilder<'m, 'c, T> where
T: Metric + From<String>,
impl<'m, 'c, T> MetricBuilder<'m, 'c, T> where
T: Metric + From<String>,
sourcepub fn with_tag(self, key: &'m str, value: &'m str) -> Self
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()
);
sourcepub fn with_tag_value(self, value: &'m str) -> Self
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()
);
sourcepub fn try_send(self) -> MetricResult<T>
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()
);
sourcepub fn send(self)
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();
Trait Implementations
Auto Trait Implementations
impl<'m, 'c, T> !RefUnwindSafe for MetricBuilder<'m, 'c, T>
impl<'m, 'c, T> Send for MetricBuilder<'m, 'c, T> where
T: Send,
impl<'m, 'c, T> Sync for MetricBuilder<'m, 'c, T> where
T: Sync,
impl<'m, 'c, T> Unpin for MetricBuilder<'m, 'c, T> where
T: Unpin,
impl<'m, 'c, T> !UnwindSafe for MetricBuilder<'m, 'c, T>
Blanket Implementations
sourceimpl<T> BorrowMut<T> for T where
T: ?Sized,
impl<T> BorrowMut<T> for T where
T: ?Sized,
const: unstable · sourcefn borrow_mut(&mut self) -> &mut T
fn borrow_mut(&mut self) -> &mut T
Mutably borrows from an owned value. Read more