Struct Metrics

pub struct Metrics<TBuildHasher = RandomState> { /* private fields */ }

A Metrics encapsulates a unit of work.

It is a record of the interesting things that happened during that unit, and the things that describe it.

A web request handler, grpc service rpc implementation or periodic job’s execution is a unit of work you should have a Metrics for.

Metrics does not deal in things like “gauges” or “counters.” It is more like a single-level trace; it works with concrete observations rather than exposing your code to aggregators.

Metrics objects are emitted through a reporter chain when they are Dropped. It is at that point that aggregation, if you’ve configured any, is performed.

Your code is responsible for putting the details of interest into the Metrics object as it encounters interesting details. You just record what you want to.

Generally prefer to record dimensions as early as possible, in case you early-out somewhere; in this way you’ll have more information in those cases.

Implementations

impl<TBuildHasher> Metrics<TBuildHasher>

where TBuildHasher: BuildHasher,

pub fn dimension(&mut self, name: impl Into<Name>, value: impl Into<Dimension>)

Record a dimension name and value pair - last write per metrics object wins!

pub fn measurement( &mut self, name: impl Into<Name>, value: impl Into<Observation>, )

Record a measurement name and value pair - last write per metrics object wins!

pub fn distribution( &mut self, name: impl Into<Name>, value: impl Into<Distribution>, )

Record a distribution name and value pair - last write per metrics object wins! Check out t-digests if you’re using a goodmetrics + timescale downstream.

pub fn sum(&mut self, name: impl Into<Name>, value: impl Into<i64>)

Record a sum. Repeated reports add together in this object.

Aggregation: Locally summed per report period.

pub fn time(&mut self, timer_name: impl Into<Name>) -> Timer

Record a time distribution in nanoseconds. Check out t-digests if you’re using a goodmetrics + timescale downstream.

The returned Timer is a scope guard.

pub fn guarded_dimension( &mut self, name: impl Into<Name>, default: impl Into<Dimension>, ) -> DimensionGuard

A dimension that you set a default for in case you drop early or something.

pub fn name(&self) -> &Name

Name of the metrics you passed in when you created it.

pub fn restart(&mut self)

Clear the structure in preparation for reuse without allocation. You still need to set the right behaviors and start times.

pub fn suppress(&mut self)

Do not report this metrics instance.

pub fn has_behavior(&self, behavior: MetricsBehavior) -> bool

Check if this metrics has that behavior.

pub unsafe fn add_behavior(&mut self, behavior: MetricsBehavior)

Safety

This function is intended to be used by MetricsFactories while creating new instances. It is not intended for use outside of infrastructure code. It is exposed in case you have something special you need to do with your allocator. You shouldn’t call this unless you know you need to and provide your own guarantees about when the behavior is added and whether it’s legal & valid

pub unsafe fn set_raw_behavior(&mut self, behavior: u32)

Safety

This function is intended to be used by MetricsFactories while creating new instances. It is not intended for use outside of infrastructure code. It is exposed in case you have something special you need to do with your allocator. You shouldn’t call this unless you know you need to and provide your own guarantees about when the behavior is added and whether it’s legal & valid

pub fn drain( &mut self, ) -> (&mut HashMap<Name, Dimension, TBuildHasher>, &mut HashMap<Name, Measurement, TBuildHasher>)

A sibling of restart(), this is a way to destructively move dimensions and measurements out of the metrics for aggregation or downstream message building.

Trait Implementations

impl<H> AsMut<Metrics<H>> for Metrics<H>

fn as_mut(&mut self) -> &mut Metrics<H>

Converts this type into a mutable reference of the (usually inferred) input type.

impl<TBuildHasher: BuildHasher + Default + Send> AsMut<Metrics<TBuildHasher>> for CachedMetrics<TBuildHasher>

fn as_mut(&mut self) -> &mut Metrics<TBuildHasher>

Converts this type into a mutable reference of the (usually inferred) input type.

impl<H> AsRef<Metrics<H>> for Metrics<H>

fn as_ref(&self) -> &Metrics<H>

Converts this type into a shared reference of the (usually inferred) input type.

impl<TBuildHasher: BuildHasher + Default + Send> AsRef<Metrics<TBuildHasher>> for CachedMetrics<TBuildHasher>

fn as_ref(&self) -> &Metrics<TBuildHasher>

Converts this type into a shared reference of the (usually inferred) input type.

impl<TBuildHasher: Debug> Debug for Metrics<TBuildHasher>

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

Formats the value using the given formatter.

impl<T> Display for Metrics<T>

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

Formats the value using the given formatter.