Macro slog_extlog::define_stats[−][src]

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),*]) => { ... };
}

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 the StatType of this statistic, for example Counter. 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 to BucketCounter, then a BucketMethod, 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, where bucket_value is the numerical value of the bucket the log falls into.