# 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 not universally supported. See below for available APIs.

## Recording API

### accumulateSamples

Accumulate the provided samples in the metric.

import org.mozilla.yourApplication.GleanMetrics.Graphics

Graphics.checkerboardPeak.accumulateSamples([23])

use glean_metrics;

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


C++

#include "mozilla/glean/GleanMetrics.h"

mozilla::glean::graphics::checkerboard_peak.AccumulateSamples({ 23 });


JavaScript

Glean.graphics.checkerboardPeak.accumulateSamples([23])


#### Limits

• The maximum value of bucket_count is 100.
• Only non-negative values may be recorded (>= 0).

#### Recorded errors

• invalid_value: If recording a negative value.

## Testing API

### testGetValue

Gets the recorded value for a given counter metric.

import org.mozilla.yourApplication.GleanMetrics.Graphics

// 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())

use glean::ErrorType;
use glean_metrics::graphics;

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


C++

#include "mozilla/glean/GleanMetrics.h"

auto data = mozilla::glean::graphics::checkerboard_peak.TestGetValue().value();
ASSERT_EQ(23UL, data.sum);


JavaScript

let data = Glean.graphics.checkerboardPeak.testGetValue();
Assert.equal(23, data.sum);


### testHasValue

Whether or not any value was recorded for a given counter metric.

import org.mozilla.yourApplication.GleanMetrics.Graphics

// Was anything recorded?
assertTrue(Graphics.checkerboardPeak.testHasValue())


### testGetNumRecordedErrors

Gets number of errors recorded for a given counter metric.

import org.mozilla.yourApplication.GleanMetrics.Graphics

/// Did the metric receive a negative value?
assertEquals(1, Graphics.checkerboardPeak.testGetNumRecordedErrors(ErrorType.InvalidValue))

use glean::ErrorType;
use glean_metrics::graphics;

// 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));


## Metric Parameters

Example custom distribution metric definition:

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
bugs:
- https://bugzilla.mozilla.org/000000
data_reviews:
- https://bugzilla.mozilla.org/show_bug.cgi?id=000000#c3
- me@mozilla.com
expires: 2020-10-01


### Extra metric parameters

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.

Custom distributions have the following optional parameters:

• unit: (String) The unit of the values in the metric. For documentation purposes only -- does not affect data collection.
• gecko_datapoint: (String) This is a Gecko-specific property. It is the name of the Gecko metric to accumulate the data from, when using the Glean SDK in a product using GeckoView.

## Simulator

Please, insert your custom data below as a JSON array.