Struct metrics_util::layers::AbsoluteLayer

pub struct AbsoluteLayer { /* fields omitted */ }

A layer for converting absolute counter values into incremental values.

In some systems, metrics are handled externally, meaning that users only have access to point-in-time snapshots of the values. This requires users to track the last value and the current value for the purposes of incrementing counters by the delta. Holding on to this data in each location is cumbersome.

AbsoluteLayer instead tracks all of this data in a single location, driven by specific metric name patterns. If a metric matches a given pattern, the layer treats it as an absolute value. It will figure out the delta between the last known value and the current value, passing only that delta along to the next layer. If the current value is not monotonic with respect to the last known value, then no value will be emitted whatsoever. This preserves the invariant of counters being monotonic.

Only counters are converted, and all other metric types are passed through unchanged. Internally, the state which holds key/value associations is protected by a mutex, so this layer is not suitable for updating absolute counters that are emitted at a very high frequency or a very large number of concurrent emissions.

Uses an Aho-Corasick automaton to efficiently match a metric key against multiple patterns at once. Patterns are matched across the entire key i.e. they are matched as substrings.

A number of options are exposed that control the underlying automaton, such as compilation to a DFA, or case sensitivity.

Implementations

impl AbsoluteLayer

pub fn from_patterns<P, I>(patterns: P) -> Self where
    P: IntoIterator<Item = I>,
    I: AsRef<str>, 

Creates a AbsoluteLayer from an existing set of patterns.

pub fn add_pattern<P>(&mut self, pattern: P) -> &mut AbsoluteLayer where
    P: AsRef<str>, 

Adds a pattern to match.

pub fn case_insensitive(&mut self, case_insensitive: bool) -> &mut AbsoluteLayer

Sets the case sensitivity used for pattern matching.

Defaults to false i.e. searches are case sensitive.

pub fn use_dfa(&mut self, dfa: bool) -> &mut AbsoluteLayer

Sets whether or not to internally use a deterministic finite automaton.

The main benefit to a DFA is that it can execute searches more quickly than a NFA (perhaps 2-4 times as fast). The main drawback is that the DFA uses more space and can take much longer to build.

Enabling this option does not change the time complexity for constructing the underlying Aho-Corasick automaton (which is O(p) where p is the total number of patterns being compiled). Enabling this option does however reduce the time complexity of non-overlapping searches from O(n + p) to O(n), where n is the length of the haystack.

In general, it’s a good idea to enable this if you’re searching a small number of fairly short patterns (~1000), or if you want the fastest possible search without regard to compilation time or space usage.

Defaults to true.

Trait Implementations

impl Default for AbsoluteLayer

fn default() -> AbsoluteLayer

Returns the “default value” for a type.

impl<R> Layer<R> for AbsoluteLayer

type Output = Absolute<R>

The output type after wrapping.

fn layer(&self, inner: R) -> Self::Output

Wraps inner based on this layer.