v811_spc009/art/libartbase/base/metrics/README.md

ART Metrics

This directory contains most of ART's metrics framework. Some portions that rely on the runtime can be found in the runtime/metrics directory.

Declaring Metrics

ART's internal metrics are listed in the ART_METRICS macro in metrics.h. Each metric has a METRIC entry which takes a name for the metric, a type (such as counter or histogram), and any additional arguments that are needed.

Counters

METRIC(MyCounter, MetricsCounter)

Counters store a single value that can be added to. This is useful for counting events, counting the total amount of time spent in a section of code, and other uses.

Accumulators

METRIC(MyAccumulator, MetricsAccumulator, type, accumulator_function)

Example:

METRIC(MaximumTestMetric, MetricsAccumulator, int64_t, std::max<int64_t>)

Accumulators are a generalization of counters that takes an accumulator function that is used to combine the new value with the old value. Common choices are the min and max function. To be valid, the accumulator function must be monotonic in its first argument. That is, if x_new == accumulator_function(x_old, y) then x_new ⪯ x_old for some ordering relation ⪯ (e.g. less-than-or-equal or greater-than-or-equal).

Histograms

METRIC(MyHistogram, MetricsHistogram, num_buckets, minimum_value, maximum_value)

Histograms divide a range into several buckets and count how many times a value falls within each bucket. They are useful for seeing the overall distribution for different events.

The num_buckets parameter affects memory usage for the histogram and data usage for exported metrics. It is recommended to keep this below 16. The minimum_value and maximum_value parameters are needed because we need to know what range the fixed number of buckets cover. We could keep track of the observed ranges and try to rescale the buckets or allocate new buckets, but this would make incrementing them more expensive than just some index arithmetic and an add. Values outside the range get clamped to the nearest bucket (basically, the two buckets on either side are infinitely long). If we see those buckets being way taller than the others, it means we should consider expanding the range.