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 booleans: Records truth values for a set of labels, for example "which a11y features are enabled?"

  • Counter: Counts how often something happens, for example "how often is the bookmarks button pressed?"

  • Labeled counters: Counts how often something happens per label, for example "how many of which kinds of crashes occurred ("uncaught_exception" or "native_code_crash")?"

  • Dual-labeled counters: Counts how often something happens per key and category, for example "how often did pings fail to upload per ping ("baseline", "events", ...) and per error type ("recoverable", "4xx", ...)?"

  • Custom Distribution: Records the distribution of a value that needs fine-grained control of how the histogram buckets are computed. For example, "What severity of checkerboarding did we show?"

  • Labeled custom distributions: Records the distribution of a value that needs fine-grained control of how the histogram buckets are computed, per label. For example, "what percentage of a paint is spent in specific phases?"

  • Datetime: Records an absolute date and time, for example "what time did the user first run the application?"

  • Event: Records individual occurrences of actions, for example "a view was opened."

  • Memory Distribution: Records the distribution of memory sizes, for example "how much memory was recovered during garbage collections?"

  • Labeled memory distributions: Records the distribution of memory sizes per label, for example "how big were network requests, per HTTP method ("GET", "POST", ...)?"

  • Object: Records structured data, for example "stack traces of threads of a crashing process."

  • Quantity: Records a single non-negative integer value, for example "the width of the display in pixels."

  • Labeled quantities: Records a non-negative integer values per label, for example "how many tabs are pinned, per tab bar ("sidebar", "horizontal_bar", ...)?"

  • Rate: Records 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."

  • String: Records a single Unicode string value, for example "the name of the OS."

  • Labeled strings: Records multiple Unicode string values, for example "which kind of errors 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."

  • Text: Records a single long Unicode text, used when the limits on String are too low. For example, "user-supplied reason for submitting a broken site report."

  • Timespan: Records how much time is spent in a single task, for example "how long did app initialization take?"

  • Timing Distribution: Records the distribution of multiple time measurements, for example "how long does it take to open a new tab?"

  • Labeled timing distributions: Records the distribution of multiple time measurements per label, for example "how long does it take to initialize an addon, per addon id?"

  • URL: Records URL-like strings, for example "what was the URL of the page with broken rendering?"

  • UUID: Records universally unique identifiers (UUIDs), for example "what is this profile's client_id?"

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 have a maximum of 111 characters, 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