Macro slog_extlog::define_stats
source · macro_rules! define_stats { ($name:ident = {$($stat:ident($($details:tt),*)),*}) => { ... }; (@single $stat:ident, BucketCounter, $desc:expr, [$($tags:tt),*], ($bmethod:ident, $blabel:expr, [$($blimits:expr),*]) ) => { ... }; (@single $stat:ident, $stype:ident, $desc:expr, [$($tags:tt),*] ) => { ... }; (@single $stat:ident, $stype:ident, $id:expr, $desc:expr, [$($tags:tt),*] ) => { ... }; (@inner $stat:ident, $stype:ident, $desc:expr, $bmethod:ident, $blabel:expr, [$($tags:tt),*], [$($blimits:expr),*]) => { ... }; }
Expand description
A macro to define the statistics that can be tracked by the logger.
Use of this macro requires StatDefinition
to be in scope.
All statistics should be defined by their library using this macro.
The syntax is as follows:
define_stats!{
STATS_LIST_NAME = {
StatName(Type, "Description", ["tag1", "tag2", ...]),
StatName2(...),
...
}
}
The STATS_LIST_NAME
is then created as a vector of definitions that can be passed in as the
stats
field on a StatsConfig
object.
Each definition in the list has the format above, with the fields as follows.
StatName
is the externally-facing metric name.Type
is theStatType
of this statistic, for exampleCounter
. Must be a valid subtype of that enum.Description
is a human readable description of the statistic. This will be logged as the log message,- The list of
tags
define field names to group the statistic by. A non-empty list indicates that this statistic should be split into groups, counting the stat separately for each different value of these fields that is seen. These might be a remote hostname, say, or a tag field.- If multiple tags are provided, the stat is counted separately for all distinct combinations of tag values.
- Use of this feature should be avoided for fields that can take very many values, such as a subscriber number, or for large numbers of tags - each tag name and seen value adds a performance dip and a small memory overhead that is never freed.
- If the
Type
field is set toBucketCounter
, then aBucketMethod
, bucket label and bucket limits must also be provided like so:
define_stats!{
STATS_LIST_NAME = {
StatName(BucketCounter, "Description", ["tag1", "tag2", ...], (BucketMethod, "bucket_label", [1, 2, 3, ...])),
StatName2(...),
...
}
}
- The
BucketMethod
determines how the stat will be sorted into numerical buckets and should - be a subtype of that enum.
- The bucket limits should be a list of
i64
values, each representing the upper bound of that bucket. - The bucket label should describe what the buckets measure and should be distinct from the tags.
Each stat log will be labelled with the pair
(bucket_label, bucket_value)
in addition to the tags, wherebucket_value
is the numerical value of the bucket the log falls into.