Custom Distribution

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_datapoint parameter is present) and thus have only a Kotlin API.

Configuration

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
histogram_type:
- linear: The buckets are evenly spaced
- exponential: The buckets follow a natural logarithmic distribution

Note Check out how these bucketing algorithms would behave on the Custom distribution simulator

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 metrics.yaml file:

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
    ...

API

Now you can use the custom distribution from the application's code.

import org.mozilla.yourApplication.GleanMetrics.Graphics

Graphics.checkerboardPeak.accumulateSamples([23])

There are test APIs available too. For convenience, properties sum and 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))


#![allow(unused)]
fn main() {
use glean_metrics;

graphics::checkerboard_peak.accumulate_samples_signed(vec![23]);
}

There are test APIs available too.


#![allow(unused)]
fn main() {
use glean::ErrorType;
use glean_metrics;

// Was anything recorded?
assert!(graphics::checkerboard_peak.test_get_value(None).is_some());
// Does it have the expected value?
assert_eq!(23, graphics::checkerboard_peak.test_get_value(None).unwrap().sum);

// Were any of the values negative and thus caused an error to be recorded?
assert_eq!(
    0,
    graphics::checkerboard_peak.test_get_num_recorded_errors(ErrorType::InvalidValue));
}