Macro stats::define_stats

macro_rules! define_stats {
    ($( $name:ident: $stat_type:tt($( $params:tt )*), )*) => { ... };
    (prefix = $prefix:expr;
     $( $name:ident: $stat_type:tt($( $params:tt )*), )*) => { ... };
}

The macro to define STATS module that contains static variables, one per counter you want to export. This is the main and recommended way to interact with statistics provided by this crate. If non empty prefix is passed then the exported counter name will be “{prefix}.{name}”

Examples:

use stats::prelude::*;
use fbinit::FacebookInit;

define_stats! {
    prefix = "my.test.counters";
    manual_c: singleton_counter(),
    test_c: counter(),
    test_c2: counter("test_c.two"),
    test_t: timeseries(Sum, Average),
    test_t2: timeseries("test_t.two"; Sum, Average),
    test_h: histogram(1, 0, 1000, Sum; P 99; P 50),
    dtest_c: dynamic_counter("test_c.{}", (job: u64)),
    dtest_t: dynamic_timeseries("test_t.{}", (region: &'static str); Rate, Sum),
    dtest_t2: dynamic_timeseries("test_t.two.{}.{}", (job: u64, region: &'static str); Count),
    dtest_h: dynamic_histogram("test_h.{}", (region: &'static str); 1, 0, 1000, Sum; P 99),
    test_qs: quantile_stat("test_qs"; Count, Sum, Average; P 95, P 99; Duration::from_secs(60)),
    test_qs_two: quantile_stat(Count, Sum, Average; P 95; Duration::from_secs(60)),
    test_dynqs: dynamic_quantile_stat("test_dynqs_{}", (num: i32); Count, Sum, Average; P 95, P 99; Duration::from_secs(60)),
}

#[allow(non_snake_case)]
mod ALT_STATS {
    use stats::define_stats;
    define_stats! {
        test_t: timeseries(Sum, Average),
        test_t2: timeseries("test.two"; Sum, Average),
    }
    pub use self::STATS::*;
}

#[fbinit::main]
fn main(fb: FacebookInit) {
    STATS::manual_c.set_value(fb, 1);
    STATS::test_c.increment_value(1);
    STATS::test_c2.increment_value(100);
    STATS::test_t.add_value(1);
    STATS::test_t2.add_value_aggregated(79, 10);  // Add 79 and note it came from 10 samples
    STATS::test_h.add_value(1);
    STATS::test_h.add_repeated_value(1, 44);  // 44 times repeat adding 1
    STATS::dtest_c.increment_value(7, (1000,));
    STATS::dtest_t.add_value(77, ("lla",));
    STATS::dtest_t2.add_value_aggregated(81, 12, (7, "lla"));
    STATS::dtest_h.add_value(2, ("frc",));

    ALT_STATS::test_t.add_value(1);
    ALT_STATS::test_t2.add_value(1);
}

Reference

singleton_counter, counter

DEPRECATED: Use timeseries instead.

Raw counter types. These take an optional key parameter - if it is not specified, then it’s derived from the stat field name.

timeseries

The general syntax for timeseries is:

timeseries(<optional key>; <list of aggregations>; [optional intervals])

If “optional key” is omitted then key is derived from the stat key name; otherwise it’s a string literal.

“List of aggregations” is a ,-separated list of AggregationType enum values.

“Optional intervals” is a ,-separated list of Durations. It specifies over what time periods the aggregations aggregate. If not specified, it typically defaults to 60 seconds.

This maps to a call to StatsManager::create_timeseries.

histogram

DEPRECATED: Use quantile_stat instead.

The general syntax for histogram is:

histogram(<optional key>; bucket-width, min, max, <list of aggregations>; <P XX percentiles>)

If “optional key” is omitted then key is derived from the stat key name; otherwise it’s a string literal.

bucket-width specifies what range of values are accumulated into each bucket; the larger it is the fewer buckets there are.

min and max specify the min and max of the expected range of samples. Samples outside this range will be aggregated into out-of-range buckets, which means they’re not lost entirely but they lead to inaccurate stats.

Together the min, max and bucket width parameters determine how many buckets are created.

“List of aggregations” is a ,-separated list of AggregationType enum values.

Percentiles are specified as P NN in a ;-separated list, such as P 20; P 50; P 90; P 99…

This maps to a call to StatsManager::create_histogram.

quantile_stat

The general syntax for quantile_stat is:

quantile_stat(<optional key>; <list of aggregations>; <P XX percentiles>; <list of intervals>)

“List of aggregations” is a ,-separated list of AggregationType enum values.

Percentiles are specified as P NN or P NN.N in a ,-separated list, such as P 20, P 50, P 90, P 99… You can also use floating point values as well such as P 95.0, P 99.0, P 99.99… Please note that you provide “percentiles” instead of rates such as 0.95 like C++ API

“List of intervals” is a ,-separated list of Durations. It specifies over what time periods the aggregations aggregate.

quantile_stat measures the same statistics as histogram, but it doesn’t require buckets to be defined ahead of time. See this workplace post for more.

This maps to a call to StatsManager::create_quantile_stat.

dynamic_counter, dynamic_timeseries, dynamic_histogram, dynamic_quantile_stat

These are equivalent to the corresponding counter/timeseries/histogram/quantile_stat above, except that they allow the key to have a dynamic component. The key is no longer optional, but is instead specified with <format-string>, (variable:type, ...). The format string is standard format!.