Labeled Memory Distributions
Labeled memory distributions are used to record different related distributions of memory sizes.
See the Memory Distribution reference for details on bucket distribution, and a histogram simulator.
Recording API
accumulate
Accumulate the provided sample in the metric.
use glean_metrics::network;
network::http_upload_bandwidth
.get(http_version)
.accumulate(self.request_size * 8.0 / 1048576.0 / send_time.as_secs());
C++
#include "mozilla/glean/GleanMetrics.h"
mozilla::network::http_upload_bandwidth
.Get(httpVersion)
.Accumulate(this.mRequestSize * 8.0 / 1048576.0 / sendTime.AsSeconds());
JavaScript
Glean.network.httpUploadBandwidth[httpVersion]
.accumulate(requestSize * 8.0 / 1048576.0 / sendTime.asSeconds())
Recorded Errors
invalid_value
: if recording a memory size that is negative or over 1 TB.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__
.
- If the label contains invalid characters. Data is still recorded to the special label
Testing API
testGetValue
Gets the recorded value for a given label in a labeled memory 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 HTTP2 samples is 42MBps.
assert_eq!(42, network::http_upload_bandwidth.get("h2").test_get_value(None).unwrap().sum);
// Assert there's only the one sample
assert_eq!(1, network::http_upload_badwidth.get("h2").test_get_value(None).unwrap().count);
// Buckets are indexed by their lower bound.
assert_eq!(1, network::http_upload_bandwidth.get("h2").test_get_value(None).unwrap().values[41]);
C++
#include "mozilla/glean/GleanMetrics.h"
const data = mozilla::glean::network::http_upload_bandwidth
.Get("h2")
.TestGetValue().value().unwrap()
ASSERT_EQ(42UL, data.sum);
JavaScript
const data = Glean.network.httpUploadBandwidth["h2"].testGetValue();
Assert.equal(42, data.sum);
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 or overlarge values instrumented.
assert_eq!(
0,
network::http_upload_bandwidth.test_get_num_recorded_errors(
ErrorType::InvalidValue,
None
)
);
Metric parameters
Example labeled memory distribution metric definition:
network:
http_upload_bandwidth:
type: labeled_memory_distribution
description: >
The upload bandwidth for requests larger than 10MB,
per HTTP protocol version.
memory_unit: megabyte
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:
- h3
- h2
- http/1.0
- http/1.1
Extra metric parameters
memory_unit
Memory distributions have an optional memory_unit
parameter,
which specifies the unit the incoming memory size values are recorded in.
The allowed values for memory_unit
are:
byte
(default)kilobyte
(= 2^10 = 1,024 bytes
)megabyte
(= 2^20 = 1,048,576 bytes
)gigabyte
(= 2^30 = 1,073,741,824 bytes
)
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 100 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 upload bandwidth rates per HTTP protocol version?
- What is the distribution of bytes received per DOM network API?
Limits
- The maximum memory size that can be recorded is 1 Terabyte (240 bytes). Larger sizes will be truncated to 1 Terabyte.
- 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__
.
- 16 different dynamic labels if no static labels are defined.
Additional labels will all record to the special label
Reference
- Rust API docs:
LabeledMetric
,MemoryDistributionMetricType