Metrics

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 ("uncaught_exception" or "native_code_crash").

  • 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.

  • URL: Used to record URL-like strings.

  • 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.

  • 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.

  • Quantity: Used to record a single non-negative integer value. For example, the width of the display in pixels.

  • Labeled Quantity: Used to record multiple non-negative integer values. For example, the dimensions 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.

  • Text: Records a single long Unicode text, used when the limits on String are too low.

  • Object: Record structured data.

Labeled metrics

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 viewCount["view1"].add() and viewCount["view2"].add().

  • When you want to count errors that might occur for a feature, you could use errorCount[errorName].add().

Labeled metrics come in two forms:

  • Static labels: The labels are specified at build time in the metrics.yaml file, in the labels parameter. 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 4096 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 Glean will be tracked. After that, any additional labels are converted to the special label __other__.

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

Label format

Labels must not exceed 71 characters in length, and may comprise any printable ASCII characters.

Adding or changing metric types

Glean has a well-defined process for requesting changes to existing metric types or suggesting the implementation of new metric types:

  1. Glean consumers need to file a bug in the Data platforms & tools::Glean Metric Types component, filling in the provided form;
  2. The triage owner of the Bugzilla component prioritizes this within 6 business days and kicks off the decision making process.
  3. Once the decision process is completed, the bug is closed with a comment outlining the decision that was made.

Deprecated metrics