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])

import org.mozilla.yourApplication.GleanMetrics.Graphics;

Graphics.INSTANCE.checkerboardPeak().accumulateSamples(listOf(23));

use glean_metrics::graphics;

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

import * as graphics from "./path/to/generated/files/graphics.js";

graphics.checkerboardPeak.accumulateSamples([23]);

C++

#include "mozilla/glean/GfxMetrics.h"

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

JavaScript

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

Limits

  • Only non-negative values may be recorded (>= 0).

Recorded errors

accumulateSingleSample

Accumulates one sample and appends it to the metric.

import org.mozilla.yourApplication.GleanMetrics.Graphics

Graphics.checkerboardPeak.accumulateSingleSample(23)

import org.mozilla.yourApplication.GleanMetrics.Graphics;

Graphics.INSTANCE.checkerboardPeak().accumulateSingleSample(23);

use glean_metrics::graphics;

graphics::checkerboard_peak.accumulate_single_sample(23);

import * as graphics from "./path/to/generated/files/graphics.js";

graphics.checkerboardPeak.accumulateSingleSample(23);

C++

#include "mozilla/glean/GfxMetrics.h"

mozilla::glean::graphics::checkerboard_peak.AccumulateSingleSample(23);

JavaScript

Glean.graphics.checkerboardPeak.accumulateSingleSample(23);

Limits

  • Only non-negative values may be recorded (>= 0).

Recorded errors

startBuffer

Experimental: Start a new histogram buffer associated with this custom distribution metric.

A histogram buffer accumulates in-memory. Data is recorded into the metric when committed. No data is collected if the buffer is abandoned.

Data is automatically committed on drop.

use glean_metrics::graphics;

let buffer = graphics::checkerboard_peak.start_buffer();

for sample in all_frames.iter() {
  buffer.accumulate(sample);
}

// Explicit or implicit drop of `buffer` commits the data.
drop(buffer);

No data is recorded when the buffer is abandoned.

use glean_metrics::graphics;

let buffer = graphics::checkerboard_peak.start_buffer();

for sample in all_frames.iter() {
  buffer.accumulate(sample);
}

buffer.abandon(); // No data is recorded.

Testing API

testGetValue

Gets the recorded value for a given custom distribution metric.
Returns a struct with counts per buckets and total sum if data is stored.
Returns a language-specific empty/null value if no data is stored. Has an optional argument to specify the name of the ping you wish to retrieve data from, except in Rust where it's required. None or no argument will default to the first value found for send_in_pings.

import org.mozilla.yourApplication.GleanMetrics.Graphics

// Get snapshot
val snapshot = Graphics.checkerboardPeak.testGetValue()

// Does the sum have the expected value?
assertEquals(23, snapshot.sum)

// Does the count have the expected value?
assertEquals(1L, snapshot.count)

// Buckets are indexed by their lower bound.
assertEquals(1L, snapshot.values[19])

import org.mozilla.yourApplication.GleanMetrics.Graphics;

// Get snapshot
val snapshot = Graphics.INSTANCE.checkerboardPeak().testGetValue();

// Does the sum have the expected value?
assertEquals(23, snapshot.sum);

// Does the count have the expected value?
assertEquals(1L, snapshot.count);

use glean_metrics::graphics;

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

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

// Buckets are indexed by their lower bound.
assert_eq!(1, snapshot.values[19])

import * as graphics from "./path/to/generated/files/graphics.js";

// Get snapshot
const snapshot = await graphics.checkerboardPeak.testGetValue();

// Does the sum have the expected value?
assert.equal(23, snapshot.sum);

// Buckets are indexed by their lower bound.
assert.equal(1, snapshot.values[19]);

C++

#include "mozilla/glean/GfxMetrics.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);

testGetNumRecordedErrors

Gets the number of errors recorded for a the custom distribution metric.

import org.mozilla.yourApplication.GleanMetrics.Graphics

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

import org.mozilla.yourApplication.GleanMetrics.Graphics;

/// Did the metric receive a negative value?
assertEquals(
    0,
    Graphics.INSTANCE.checkerboardPeak().testGetNumRecordedErrors(
        ErrorType.INVALID_VALUE
    )
)

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,
        None
    )
);

import * as graphics from "./path/to/generated/files/graphics.js";
import { ErrorType } from "@mozilla/glean/<platform>";

// Did the metric receive a negative value?
assert.equal(
    0,
    graphics.checkerboardPeak.testGetNumRecordedErrors(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
    notification_emails:
      - 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 a Glean SDK in a product using GeckoView.

Reference

Simulator

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

Using these parameters, the widest bucket's width is 136.

Data options

Properties