• Home
Name
Date
Size
#Lines
LOC

..--

README.mdD06-Sep-20242.2 KiB5337

metrics.hD06-Sep-202427.9 KiB787507

metrics_common.ccD06-Sep-202412.7 KiB343273

metrics_test.ccD06-Sep-202428.3 KiB758605

metrics_test.hD06-Sep-20243 KiB8950

README.md

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