Struct metrix::cockpit::Cockpit

pub struct Cockpit<L> { /* fields omitted */ }

A cockpit groups panels.

Use a cockpit to group panels that are somehow related. Since the Cockpit is generic over its label you can use an enum as a label for grouping panels easily.

Example

Imagine you have a HTTP component that makes requests to another service and you want to track successful and failed requests individually.

use std::time::Instant;
use metrix::{Observation, HandlesObservations};
use metrix::instruments::*;
use metrix::cockpit::*;

#[derive(Clone, PartialEq, Eq)]
enum Request {
    Successful,
    Failed,
}

let counter = Counter::new_with_defaults("count");
let gauge = Gauge::new_with_defaults("last_latency");
let meter = Meter::new_with_defaults("per_second");
let histogram = Histogram::new_with_defaults("latencies");

assert_eq!(0, counter.get());
assert_eq!(None, gauge.get());

let mut success_panel = Panel::with_name(Request::Successful,
"succesful_requests"); success_panel.set_counter(counter);
success_panel.set_gauge(gauge);
success_panel.set_meter(meter);
success_panel.set_histogram(histogram);

let counter = Counter::new_with_defaults("count");
let gauge = Gauge::new_with_defaults("last_latency");
let meter = Meter::new_with_defaults("per_second");
let histogram = Histogram::new_with_defaults("latencies");

assert_eq!(0, counter.get());
assert_eq!(None, gauge.get());

let mut failed_panel = Panel::with_name(Request::Failed, "failed_requests");
failed_panel.set_counter(counter);
failed_panel.set_gauge(gauge);
failed_panel.set_meter(meter);
failed_panel.set_histogram(histogram);

let mut cockpit = Cockpit::new("requests", None);
cockpit.add_panel(success_panel);
cockpit.add_panel(failed_panel);

let observation = Observation::ObservedOneValue {
    label: Request::Successful,
    value: 100,
    timestamp: Instant::now(),
};

cockpit.handle_observation(&observation);

{
    let panels = cockpit.panels();
    let success_panel = panels
        .iter()
        .find(|p| p.label() == &Request::Successful)
        .unwrap();

    assert_eq!(Some(1), success_panel.counter().map(|c| c.get()));
    assert_eq!(Some(100), success_panel.gauge().and_then(|g| g.get()));
}

let observation = Observation::ObservedOneValue {
    label: Request::Failed,
    value: 667,
    timestamp: Instant::now(),
};

cockpit.handle_observation(&observation);

let panels = cockpit.panels();
let failed_panel = panels
    .iter()
    .find(|p| p.label() == &Request::Failed)
    .unwrap();

assert_eq!(Some(1), failed_panel.counter().map(|c| c.get()));
assert_eq!(Some(667), failed_panel.gauge().and_then(|g| g.get()));

Methods

impl<L> Cockpit<L> where
    L: Clone + Eq + Send + 'static, 

pub fn new<T: Into<String>>(
    name: T,
    value_scaling: Option<ValueScaling>
) -> Cockpit<L>

Creates a new instance.

Even though the name is optional it is suggested to use a name for a cockpit since in most cases a Cockpit is a meaningful grouping for panels and instruments.

pub fn without_name(value_scaling: Option<ValueScaling>) -> Cockpit<L>

Creates a new Cockpit without a name.

This will have the effect that there will be no grouping in the snapshot around the contained components.

pub fn with_value_scaling<T: Into<String>>(
    &mut self,
    name: T,
    value_scaling: ValueScaling
) -> Cockpit<L>

Creates a new Cockpit with a name and a ValueScaling.

The scaling is calculated on the value of Observation::ObservedOneValue prior to delegating the Observation to the Panels. If the containing components also do a value scaling, the scaling will be applied multiple times which is most likely wrong.

pub fn without_value_scaling<T: Into<String>>(&mut self, name: T) -> Cockpit<L>

Creates a new Cockpit with just a name.

pub fn name(&self) -> Option<&str>

Returns the name of this cockpit.

If there is a name set, this will group the inner components in the snapshot.

pub fn set_name<T: Into<String>>(&mut self, name: T)

Sets a name for this Cockpit. This will also enable grouping.

pub fn set_title<T: Into<String>>(&mut self, title: T)

Sets the title which will be displayed if a descriptive snaphot is requested.

pub fn set_description<T: Into<String>>(&mut self, description: T)

Sets the description which will be displayed if a descriptive snaphot is requested.

pub fn set_value_scaling(&mut self, value_scaling: ValueScaling)

Set and enable value scaling.

pub fn set_inactivity_limit(&mut self, limit: Duration)

Sets the maximum amount of time this cockpit may be inactive until no more snapshots are taken

pub fn add_panel(&mut self, panel: Panel<L>)

Add a Panel to this cockpit.

A Panel will receive only those Observations wher labels match.

There can be multiple Panels for the same label.

pub fn panels(&self) -> Vec<&Panel<L>>

Returns the Panels

pub fn panels_mut(&mut self) -> Vec<&mut Panel<L>>

Returns the Panels mutable

pub fn add_handler<T>(&mut self, handler: T) where
    T: HandlesObservations<Label = L>, 

Add a handler. This can be custom logic for metrics.

A handler will be passed all Observations unlike a Panel which will only receive Observations where the label matches.

pub fn handlers(&self) -> Vec<&dyn HandlesObservations<Label = L>>

Returns all the handlers.

pub fn add_snapshooter<T: PutsSnapshot>(&mut self, snapshooter: T)

Adds a snapshooter.

A snapshooter will only be invoked when a Snapshot is requested. It will never receive an Observation.

pub fn snapshooters(&self) -> Vec<&dyn PutsSnapshot>

Returns all snapshooters.

Trait Implementations

impl<L> HandlesObservations for Cockpit<L> where
    L: Clone + Eq + Send + 'static, 

type Label = L

fn handle_observation(
    &mut self,
    observation: &Observation<Self::Label>
) -> usize

impl<L> Descriptive for Cockpit<L>

fn title(&self) -> Option<&str>

fn description(&self) -> Option<&str>

impl<L> PutsSnapshot for Cockpit<L> where
    L: Clone + Eq + Send + 'static, 

fn put_snapshot(&self, into: &mut Snapshot, descriptive: bool)

Puts the current snapshot values into the given Snapshot thereby following the guidelines of PutsSnapshot.

impl<L> Default for Cockpit<L> where
    L: Clone + Eq + Send + 'static, 

fn default() -> Cockpit<L>

Returns the "default value" for a type.