Custom distributions are used to record the distribution of arbitrary values.
It should be used only when direct control over how the histogram buckets are computed is required. Otherwise, look at the standard distribution metric types:
Note: Custom distributions are currently only allowed for GeckoView metrics (the
gecko_datapointparameter is present) and thus have only a Kotlin API.
Custom distributions have the following required parameters:
range_min: (Integer) The minimum value of the first bucket
range_max: (Integer) The minimum value of the last bucket
bucket_count: (Integer) The number of buckets
linear: The buckets are evenly spaced
exponential: The buckets follow a natural logarithmic distribution
In addition, the metric should specify:
unit: (String) The unit of the values in the metric. For documentation purposes only -- does not affect data collection.
If you wanted to create a custom distribution of the peak number of pixels used during a checkerboard event, first you need to add an entry for it to the
graphics: checkerboard_peak: type: custom_distribution description: > Peak number of CSS pixels checkerboarded during a checkerboard event. range_min: 1 range_max: 66355200 bucket_count: 50 histogram_type: exponential unit: pixels gecko_datapoint: CHECKERBOARD_PEAK ...
Now you can use the custom distribution from the application's code.
import org.mozilla.yourApplication.GleanMetrics.Graphics Graphics.checkerboardPeak.accumulateSamples()
There are test APIs available too. For convenience, properties
count are exposed to facilitate validating that data was recorded correctly.
import org.mozilla.yourApplication.GleanMetrics.Graphics // Was anything recorded? assertTrue(Graphics.checkerboardPeak.testHasValue()) // Get snapshot val snapshot = Graphics.checkerboardPeak.testGetValue() // Does the sum have the expected value? assertEquals(11, snapshot.sum) // Usually you don't know the exact timing values, but how many should have been recorded. assertEquals(2L, snapshot.count()) /// Did the metric receive a negative value? assertEquals(1, Graphics.checkerboardPeak.testGetNumRecordedErrors(ErrorType.InvalidValue))
The maximum value of
Only non-negative values may be recorded.
invalid_value: If recording a negative value.