Labeled Custom Distributions

Labeled custom distributions are used to record different related distributions of arbitrary values.

If your data is timing or memory based and you don't need direct control over histogram buckets, consider instead:

Recording API

`accumulateSamples`

Accumulate the provided samples in the metric.

use glean_metrics::network;

network::http3_late_ack_ratio
    .get("ack")
    .accumulateSamples(vec![(stats.late_ack * 10000) / stats.packets_tx]);
network::http3_late_ack_ratio
    .get("pto")
    .accumulateSamples(vec![(stats.pto_ack * 10000) / stats.packets_tx]);

C++

#include "mozilla/glean/GleanMetrics.h"

mozilla::glean::network::http3_late_ack_ratio
    .Get("ack")
    .AccumulateSamples({(stats.late_ack * 10000) / stats.packets_tx});
mozilla::glean::network::http3_late_ack_ratio
    .Get("pto")
    .AccumulateSamples({(stats.pto_ack * 10000) / stats.packets_tx});

JavaScript

Glean.network.http3LateAckRatio["ack"]
  .accumulateSamples([(stats.late_ack * 10000) / stats.packets_tx]);
Glean.network.http3LateAckRatio["pto"]
  .accumulateSamples([(stats.pto_ack * 10000) / stats.packets_tx]);

Recorded Errors

invalid_value: if recording any negative samples
invalid_label:
- If the label contains invalid characters. Data is still recorded to the special label __other__.
- If the label exceeds the maximum number of allowed characters. Data is still recorded to the special label __other__.

`accumulateSingleSample`

Accumulates one sample and appends it to the metric.

use glean_metrics::network;

network::http3_late_ack_ratio
    .get("ack")
    .accumulateSingleSample((stats.late_ack * 10000) / stats.packets_tx);
network::http3_late_ack_ratio
    .get("pto")
    .accumulateSingleSample((stats.pto_ack * 10000) / stats.packets_tx);

C++

#include "mozilla/glean/GleanMetrics.h"

mozilla::glean::network::http3_late_ack_ratio
    .Get("ack")
    .AccumulateSingleSample((stats.late_ack * 10000) / stats.packets_tx);
mozilla::glean::network::http3_late_ack_ratio
    .Get("pto")
    .AccumulateSingleSample((stats.pto_ack * 10000) / stats.packets_tx);

JavaScript

Glean.network.http3LateAckRatio["ack"]
  .accumulateSingleSample((stats.late_ack * 10000) / stats.packets_tx);
Glean.network.http3LateAckRatio["pto"]
  .accumulateSingleSample((stats.pto_ack * 10000) / stats.packets_tx);

Recorded Errors

invalid_value: if recording a negative sample
invalid_label:
- If the label contains invalid characters. Data is still recorded to the special label __other__.
- If the label exceeds the maximum number of allowed characters. Data is still recorded to the special label __other__.

Gets the recorded value for a given label in a labeled 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.

use glean_metrics::network;

// Assert the sum of all samples is 42.
assert_eq!(42, network::http3_late_ack_ratio.get("ack").test_get_value(None).unwrap().sum);

// Assert there's only the one sample
assert_eq!(1, network::http3_late_ack_ratio.get("ack").test_get_value(None).unwrap().count);

// Buckets are indexed by their lower bound.
assert_eq!(1, network::http3_late_ack_ratio.get("ack").test_get_value(None).unwrap().values[41]);

C++

#include "mozilla/glean/GleanMetrics.h"

auto data = mozilla::glean::network::http3_late_ack_ratio.Get("ack").TestGetValue().value();
ASSERT_EQ(42UL, data.sum);
ASSERT_EQ(1, data.count);
ASSERT_EQ(1, data.values[41]);

JavaScript

let data = Glean.network.http3LateAckRatio["ack"].testGetValue();
Assert.equal(42, data.sum);
Assert.equal(1, data.count);
Assert.equal(1, data.values[41]);

`testGetNumRecordedErrors`

Gets the number of errors recorded for a given labeled custom distribution metric in total.

use glean::ErrorType;
use glean_metrics::network;

// Assert there were no negative values instrumented.
assert_eq!(
    0,
    network::http3_late_ack_ratio.test_get_num_recorded_errors(
        ErrorType::InvalidValue,
        None
    )
);

Metric parameters

Example labeled custom distribution metric definition:

network:
  http3_late_ack_ratio:
    type: labeled_custom_distribution
    description: >
      HTTP3: The ratio of spurious retransmissions per packets sent,
      represented as an integer permdecimille:
      `(spurious_retransmission / packet sent * 10000)`
    range_min: 1
    range_max: 2000
    bucket_count 100
    histogram_type: exponential
    bugs:
      - https://bugzilla.mozilla.org/000000
    data_reviews:
      - https://bugzilla.mozilla.org/show_bug.cgi?id=000000#c3
    notification_emails:
      - me@mozilla.com
    expires: 175
    labels:
      - ack
      - pto

Extra metric parameters

`range_min`, `range_max`, `bucket_count`, and `histogram_type` (Required)

Labeled 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

`labels`

Labeled metrics may have an optional labels parameter, containing a list of known labels. The labels in this list must match the following requirements:

Conform to the label format.
Each label must have a maximum of 71 characters.
Each label must only contain printable ASCII characters.
This list itself is limited to 4096 labels.

Important

If the labels are specified in the metrics.yaml, using any label not listed in that file will be replaced with the special value __other__.

If the labels are not specified in the metrics.yaml, only 16 different dynamic labels may be used, after which the special value __other__ will be used.

Removing or changing labels, including their order in the registry file, is permitted. Avoid reusing labels that were removed in the past. It is best practice to add documentation about removed labels to the description field so that analysts will know of their existence and meaning in historical data. Special care must be taken when changing GeckoView metrics sent through the Glean SDK, as the index of the labels is used to report Gecko data through the Glean SDK.

Data questions

What is the distribution of retransmission ratios per connection?
What is the distribution of how long it takes to load extensions' content scripts, by addon id?

Limits

The maximum value of bucket_count is 100.
Only non-negative integer values may be recorded (>=0).
Labels must conform to the label format.
Each label must have a maximum of 71 characters.
Each label must only contain printable ASCII characters.
The list of labels is limited to:
- 16 different dynamic labels if no static labels are defined. Additional labels will all record to the special label __other__.
- 100 labels if specified as static labels in metrics.yaml, see Labels. Unknown labels will be recorded under the special label __other__.

Reference

Rust API docs: LabeledMetric, CustomDistributionMetricType

Glean SDKs - Cross-platform Telemetry Libraries

Labeled Custom Distributions

Recording API

`accumulateSamples`

Recorded Errors

`accumulateSingleSample`

Recorded Errors

Testing API

`testGetValue`

`testGetNumRecordedErrors`

Metric parameters

Extra metric parameters

`range_min`, `range_max`, `bucket_count`, and `histogram_type` (Required)

`labels`

Important

Data questions

Limits

Reference