1# ART Metrics
2
3This directory contains most of ART's metrics framework. Some portions that
4rely on the runtime can be found in the `runtime/metrics` directory.
5
6## Declaring Metrics
7
8ART's internal metrics are listed in the `ART_METRICS` macro in `metrics.h`.
9Each metric has a `METRIC` entry which takes a name for the metric, a type
10 (such as counter or histogram), and any additional arguments that are needed.
11
12### Counters
13
14    METRIC(MyCounter, MetricsCounter)
15
16Counters store a single value that can be added to. This is useful for counting
17events, counting the total amount of time spent in a section of code, and other
18uses.
19
20### Accumulators
21
22    METRIC(MyAccumulator, MetricsAccumulator, type, accumulator_function)
23
24Example:
25
26    METRIC(MaximumTestMetric, MetricsAccumulator, int64_t, std::max<int64_t>)
27
28Accumulators are a generalization of counters that takes an accumulator
29function that is used to combine the new value with the old value. Common
30choices are the min and max function. To be valid, the accumulator function
31must be monotonic in its first argument. That is, if
32`x_new == accumulator_function(x_old, y)` then `x_new ⪯ x_old` for some
33ordering relation `⪯` (e.g. less-than-or-equal or greater-than-or-equal).
34
35### Histograms
36
37    METRIC(MyHistogram, MetricsHistogram, num_buckets, minimum_value, maximum_value)
38
39Histograms divide a range into several buckets and count how many times a value
40falls within each bucket. They are useful for seeing the overall distribution
41for different events.
42
43The `num_buckets` parameter affects memory usage for the histogram and data
44usage for exported metrics. It is recommended to keep this below 16. The
45`minimum_value` and `maximum_value` parameters are needed because we need to
46know what range the fixed number of buckets cover. We could keep track of the
47observed ranges and try to rescale the buckets or allocate new buckets, but
48this would make incrementing them more expensive than just some index
49arithmetic and an add. Values outside the range get clamped to the nearest
50bucket (basically, the two buckets on either side are infinitely long). If we
51see those buckets being way taller than the others, it means we should consider
52expanding the range.
53