Not sure which metric type to use? These docs contain a series of questions that can help. Reference information about each metric type is linked below.
The parameters available that apply to any metric type are in the metric parameters page.
There are different metrics to choose from, depending on what you want to achieve:
Boolean: Records a single truth value, for example "is a11y enabled?"
Labeled boolean: Records truth values for a set of labels, for example "which a11y features are enabled?"
Counter: Used to count how often something happens, for example, how often a certain button was pressed.
Labeled counter: Used to count how often something happens, for example which kind of crash occurred (
String: Records a single Unicode string value, for example the name of the OS.
Labeled strings: Records multiple Unicode string values, for example to record which kind of error occurred in different stages of a login process.
String List: Records a list of Unicode string values, for example the list of enabled search engines.
Timespan: Used to measure how much time is spent in a single task.
Timing Distribution: Used to record the distribution of multiple time measurements.
Memory Distribution: Used to record the distribution of memory sizes.
UUID: Used to record universally unique identifiers (UUIDs), such as a client ID.
Datetime: Used to record an absolute date and time, such as the time the user first ran the application.
Events: Records events e.g. individual occurrences of user actions, say every time a view was open and from where.
Quantity: Used to record a single non-negative integer value. For example, the width of the display in pixels.
Rate: Used to record the rate something happens relative to some other thing. For example, the number of HTTP connections that experienced an error relative to the number of total HTTP connections made.
Custom Distribution: Used to record the distribution of a value that needs fine-grained control of how the histogram buckets are computed. Custom distributions are only available for values that come from Gecko.
There are two types of metrics listed above - labeled and unlabeled metrics. If a metric is labeled, it means that for a single metric entry you define in
metrics.yaml, you can record into multiple metrics under the same name, each of the same type and identified by a different string label.
This is useful when you need to break down metrics by a label known at build time or run time. For example:
When you want to count a different set of sub-views that users interact with, you could use
When you want to count errors that might occur for a feature, you could use
Labeled metrics come in two forms:
Static labels: The labels are specified at build time in the
metrics.yamlfile, in the
labelsparameter. If a label that isn't part of this set is used at run time, it is converted to the special label
__other__. The number of static labels is limited to 100 per metric.
Dynamic labels: The labels aren't known at build time, so are set at run time. Only the first 16 labels seen by the Glean SDK will be tracked. After that, any additional labels are converted to the special label
Note: Be careful with using arbitrary strings as labels and make sure they can't accidentally contain identifying data (like directory paths or user input).
To ensure maximum support in database columns, labels must be made up of dot-separated identifiers with lowercase ASCII alphanumerics, containing underscores and dashes.
Specifically, they must conform to this regular expression:
Glean has a well-defined process for requesting changes to existing metric types or suggesting the implementation of new metric types:
- Glean consumers need to file a bug in the Data platforms & tools::Glean Metric Types component, filling in the provided form;
- The triage owner of the Bugzilla component prioritizes this within 6 business days and kicks off the decision making process.
- Once the decision process is completed, the bug is closed with a comment outlining the decision that was made.