Struct cadence::MetricBuilder

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

Builder for adding tags to in-progress metrics.

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

This builder adds tags, key-value pairs or just values, to a metric that was previously constructed by a called to method on StatsdClient. The tags are added to metrics and sent via the client when MetricBuilder::send() is invoked. Adding tags via this builder will typically result in one or more extra heap allocations.

Any errors countered constructing or validating the metrics will be propagated here through the ::send() call.

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

Example

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.incr_with_tags("some.key")
   .with_tag("host", "app11.example.com")
   .with_tag("segment", "23")
   .with_tag_value("beta")
   .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.

Methods

impl<'m, 'c, T> MetricBuilder<'m, 'c, T> where
    T: Metric + From<String>, 

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.decr_with_tags("some.key")
   .with_tag("type", "user-signup")
   .send();

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

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")
   .send();

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

fn 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 .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")
   .send();

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

Trait Implementations

impl<'m, 'c, T: Debug> Debug for MetricBuilder<'m, 'c, T> where
    T: Metric + From<String>, 

fn fmt(&self, __arg_0: &mut Formatter) -> Result

Formats the value using the given formatter.