Struct cernan::metric::Telemetry

pub struct Telemetry {
    pub name: String,
    pub persist: bool,
    pub timestamp: i64,
    // some fields omitted
}

A Telemetry is a name, tagmap, timestamp and aggregated, point-in-time value, as outlined in the cernan native protocol.

Fields

name: String

The name of the Telemetry. This is user-provided and will vary by input protocol.

persist: bool

Determine whether the Telemetry will persist across time bins.

timestamp: i64

The time of Telemetry, measured in seconds.

Methods

impl Telemetry

pub fn new() -> SoftTelemetry

Make a builder for metrics

This function returns a TelemetryBuidler with a name set. A metric must have at least a name and a value but values may be delayed behind names.

Examples

use cernan::metric::{AggregationMethod, Telemetry};

let m = Telemetry::new().name("foo").value(1.1).harden().unwrap();

assert_eq!(m.kind(), AggregationMethod::Set);
assert_eq!(m.name, "foo");
assert_eq!(m.set(), Some(1.1));

pub fn thaw(self) -> SoftTelemetry

Unfreeze a Telemetry into a SoftTelemetry

Telemetry is a central type to cernan. There's a great deal of validation that needs to happen whenever we change one of these things and, well, there's a lot of changing going on. For the most part Telemetry is a read-only type and it must be 'unfrozen' to be changed.

pub fn kind(&self) -> AggregationMethod

Return the kind of the Telemetry

This method is useful for determing the available operations over Telemetry, creating partitions of streams or for any other instance where you need to know what kind of aggregation is happening.

Important traits for TagIter<'a>

impl<'a> Iterator for TagIter<'a> type Item = (&'a String, &'a String);

pub fn tags<'a>(&'a self, defaults: &'a TagMap) -> TagIter<'a>

Iterate tags, layering in defaults when needed

The defaults serves to fill 'holes' in the Telemetry's view of the tags. We avoid shipping tags through the whole system at the expense of slightly more complicated call-sites in sinks.

pub fn get_from_tags<'a>(     &'a mut self,     key: &'a str,     defaults: &'a TagMap ) -> Option<&'a String>

Get a value from tags, either interior or default

pub fn insert_tag<S>(&mut self, key: S, val: S) -> Option<String> where     S: Into<String>,

Insert a tag into the Telemetry

This inserts a key/value pair into the Telemetry, returning the previous value if the key already existed.

pub fn remove_tag(&mut self, key: &str) -> Option<String>

Remove a tag from the Telemetry

This removes a key/value pair from the Telemetry, returning the previous value if the key existed.

pub fn overlay_tag<S>(self, key: S, val: S) -> Telemetry where     S: Into<String>,

Overlay a specific key / value pair in self's tags

This insert a key / value pair into the metric's tag map. If the key was already present in the tag map the value will be replaced, else it will be inserted.

pub fn overlay_tags_from_map(self, map: &TagMap) -> Telemetry

Overlay self's tags with a TagMap

This inserts a map of key / value pairs over the top of metric's existing tag map. Any new keys will be inserted while existing keys will be overwritten.

pub fn insert(self, value: f64) -> Telemetry

Insert a value into the Telemetry

The inserted value will be subject to the Telemetry's aggregation method.

pub fn sum(&self) -> Option<f64>

Return the sum value of a SUM, None otherwise

pub fn set(&self) -> Option<f64>

Return the set value of a SET, None otherwise

pub fn query(&self, prcnt: f64) -> Option<f64>

Query a CKMS for a percentile, return None if not SUMMARIZE

pub fn bins(&self) -> Option<Iter<f64>>

Retrieve the bins of a BIN, None if not BIN

pub fn samples_sum(&self) -> Option<f64>

Sum of all samples inserted into this Telemetry

pub fn count(&self) -> usize

Return the total count of Telemetry aggregated into this Telemetry.

pub fn mean(&self) -> f64

Return the mean value of all Telemetry aggregated in this Telemetry.

Important traits for Vec<u8>

impl Write for Vec<u8>

pub fn samples(&self) -> Vec<f64>

Return a vector of stored Telemetry values

This method is subject to data loss. Consider aggregating into a SET. The Telemetry is allowed to retain only one value -- the last -- and calling samples in that case will return only the last value aggregated into the Telemetry.

pub fn within(&self, span: i64, other: &Telemetry) -> Ordering

Determine if two Telemetry are within one 'span' of one another.

This method determines if 1. two telemetry are 'alike' by name, tags and aggregation and 2. if their timestamps are within one span bound of one another.

pub fn is_zeroed(&self) -> bool

Determine if the Telemetry's contained aggregation is valued zero.

pub fn hash(&self) -> u64

Return a hash of the Telemetry

The hash of a telemetry is based on its 'alike' fields. That is, its name, tags and aggregation kind.

pub fn name_tag_hash(&self) -> u64

Return a hash only of name and tags

This method is very near to Telemetry::hash but that aggregation kind is ignored. This is useful for producing a hash for storage in some kinds of lookup maps, say flush_boundary_filter where only storage takes place, not aggregation.

pub fn is_set(&self) -> bool

Returns true if aggregation method is SET

pub fn is_histogram(&self) -> bool

Returns true if aggregation method is BINS

pub fn is_sum(&self) -> bool

Returns true if aggregation method is SUM

pub fn is_summarize(&self) -> bool

Returns true if aggregation method is SUMMARIZE

pub fn timestamp(self, time: i64) -> Telemetry

Adjust Telemetry time

This sets the metric time to the specified value, taken to be UTC seconds since the Unix Epoch. If this is not set the metric will default to cernan::time::now().

Examples

use cernan::metric::Telemetry;

let m = Telemetry::new()
    .name("foo")
    .value(1.1)
    .harden()
    .unwrap()
    .timestamp(10101);

assert_eq!(10101, m.timestamp);

Trait Implementations

impl PartialEq for Telemetry

fn eq(&self, other: &Telemetry) -> bool

This method tests for self and other values to be equal, and is used by ==.

fn ne(&self, other: &Telemetry) -> bool

This method tests for !=.

impl Debug for Telemetry

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

Formats the value using the given formatter.

impl Clone for Telemetry

fn clone(&self) -> Telemetry

Returns a copy of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl AddAssign for Telemetry

fn add_assign(&mut self, rhs: Telemetry)

Performs the += operation.

impl PartialOrd for Telemetry

fn partial_cmp(&self, other: &Telemetry) -> Option<Ordering>

This method returns an ordering between self and other values if one exists.

fn lt(&self, other: &Rhs) -> bool

This method tests less than (for self and other) and is used by the < operator.

fn le(&self, other: &Rhs) -> bool

This method tests less than or equal to (for self and other) and is used by the <= operator.

fn gt(&self, other: &Rhs) -> bool

This method tests greater than (for self and other) and is used by the > operator.

fn ge(&self, other: &Rhs) -> bool

This method tests greater than or equal to (for self and other) and is used by the >= operator.

impl Default for Telemetry

fn default() -> Telemetry

Returns the "default value" for a type.