metrics.yaml

# This Source Code Form is subject to the terms of the Mozilla Public
# License, v. 2.0. If a copy of the MPL was not distributed with this
# file, You can obtain one at http://mozilla.org/MPL/2.0/.

# This file defines the metrics that are recorded by the Glean SDK.
# APIs to use these pings are automatically generated at build time using
# the `glean_parser` PyPI package.

# Metrics in this file may make use of SDK reserved ping names. See
# https://mozilla.github.io/glean/book/dev/core/internal/reserved-ping-names.html
# for additional information.

---
$schema: moz://mozilla.org/schemas/glean/metrics/2-0-0

glean.baseline:
  duration:
    type: timespan
    description: |
      The duration of the last foreground session.
    time_unit: second
    send_in_pings:
      - baseline
    bugs:
      - https://bugzilla.mozilla.org/1497894
      - https://bugzilla.mozilla.org/1519120
    data_reviews:
      - https://bugzilla.mozilla.org/show_bug.cgi?id=1512938#c3
    data_sensitivity:
      - technical
      - interaction
    notification_emails:
      - glean-team@mozilla.com
    expires: never

glean.internal.metrics:
  os:
    type: string
    lifetime: application
    send_in_pings:
      - glean_client_info
    description: |
      The name of the operating system.
      Possible values:
      Android, iOS, Linux, Darwin, Windows,
      FreeBSD, NetBSD, OpenBSD, Solaris, unknown
    bugs:
      - https://bugzilla.mozilla.org/1497894
    data_reviews:
      - https://bugzilla.mozilla.org/show_bug.cgi?id=1512938#c3
    data_sensitivity:
      - technical
    notification_emails:
      - glean-team@mozilla.com
    expires: never

  os_version:
    type: string
    lifetime: application
    send_in_pings:
      - glean_client_info
    description: |
      The user-visible version of the operating system (e.g. "1.2.3"). If the
      version detection fails, this metric gets set to `Unknown`.
    bugs:
      - https://bugzilla.mozilla.org/1497894
    data_reviews:
      - https://bugzilla.mozilla.org/show_bug.cgi?id=1512938#c3
    data_sensitivity:
      - technical
    notification_emails:
      - glean-team@mozilla.com
    expires: never

  device_manufacturer:
    type: string
    lifetime: application
    send_in_pings:
      - glean_client_info
    description: |
      The manufacturer of the device the application is running on.
      Not set if the device manufacturer can't be determined (e.g. on Desktop).
    bugs:
      - https://bugzilla.mozilla.org/1522552
    data_reviews:
      - https://bugzilla.mozilla.org/show_bug.cgi?id=1512938#c3
    data_sensitivity:
      - technical
    notification_emails:
      - glean-team@mozilla.com
    expires: never

  device_model:
    type: string
    lifetime: application
    send_in_pings:
      - glean_client_info
    description: |
      The model of the device the application is running on.
      On Android, this is Build.MODEL, the user-visible marketing name,
      like "Pixel 2 XL".
      Not set if the device model can't be determined (e.g. on Desktop).
    bugs:
      - https://bugzilla.mozilla.org/1522552
    data_reviews:
      - https://bugzilla.mozilla.org/show_bug.cgi?id=1512938#c3
    data_sensitivity:
      - technical
    notification_emails:
      - glean-team@mozilla.com
    expires: never

  architecture:
    type: string
    lifetime: application
    send_in_pings:
      - glean_client_info
    description: |
      The architecture of the device, (e.g. "arm", "x86").
    bugs:
      - https://bugzilla.mozilla.org/1497894
    data_reviews:
      - https://bugzilla.mozilla.org/show_bug.cgi?id=1512938#c3
    data_sensitivity:
      - technical
    notification_emails:
      - glean-team@mozilla.com
    expires: never

  client_id:
    type: uuid
    description:
      A UUID uniquely identifying the client.
    send_in_pings:
      - glean_client_info
    lifetime: user
    bugs:
      - https://bugzilla.mozilla.org/1497894
    data_reviews:
      - https://bugzilla.mozilla.org/show_bug.cgi?id=1512938#c3
    data_sensitivity:
      - technical
    notification_emails:
      - glean-team@mozilla.com
    expires: never

  app_build:
    type: string
    lifetime: application
    send_in_pings:
      - glean_client_info
    description: |
      The build identifier generated by the CI system (e.g. "1234/A").
      For language bindings that provide automatic detection for this value,
      (e.g. Android/Kotlin), in the unlikely event that the build identifier
      can not be retrieved from the OS, it is set to "inaccessible". For other
      language bindings, if the value was not provided through configuration,
      this metric gets set to `Unknown`.
    bugs:
      - https://bugzilla.mozilla.org/1508305
    data_reviews:
      - https://bugzilla.mozilla.org/show_bug.cgi?id=1512938#c3
    data_sensitivity:
      - technical
    notification_emails:
      - glean-team@mozilla.com
    expires: never

  app_display_version:
    type: string
    lifetime: application
    send_in_pings:
      - glean_client_info
    description: |
      The user visible version string (e.g. "1.0.3").

      In the unlikely event that the display version can not be retrieved,
      it is set to "inaccessible".
    bugs:
      - https://bugzilla.mozilla.org/1508305
    data_reviews:
      - https://bugzilla.mozilla.org/show_bug.cgi?id=1508305#c9
    data_sensitivity:
      - technical
    notification_emails:
      - glean-team@mozilla.com
    expires: never

  app_channel:
    type: string
    lifetime: application
    send_in_pings:
      - glean_client_info
    description: |
      The channel the application is being distributed on.
    bugs:
      - https://bugzilla.mozilla.org/1520741
    data_reviews:
      - https://bugzilla.mozilla.org/show_bug.cgi?id=1520741#c18
    data_sensitivity:
      - technical
    notification_emails:
      - glean-team@mozilla.com
    expires: never

  first_run_date:
    type: datetime
    lifetime: user
    send_in_pings:
      - glean_client_info
    time_unit: day
    description: |
      The date of the first run of the application.
    bugs:
      - https://bugzilla.mozilla.org/1525045
    data_reviews:
      - https://bugzilla.mozilla.org/show_bug.cgi?id=1525045#c18
    data_sensitivity:
      - technical
    notification_emails:
      - glean-team@mozilla.com
    expires: never

  locale:
    type: string
    lifetime: application
    send_in_pings:
      - glean_client_info
    description: |
      The locale of the application during initialization (e.g. "es-ES").
      If the locale can't be determined on the system, the value is
      ["und"](https://unicode.org/reports/tr35/#Unknown_or_Invalid_Identifiers),
      to indicate "undetermined".
    bugs:
      - https://bugzilla.mozilla.org/1601489
    data_reviews:
      - https://bugzilla.mozilla.org/show_bug.cgi?id=1601489#c3
    data_sensitivity:
      - technical
      - interaction
    notification_emails:
      - glean-team@mozilla.com
    expires: never

  seq:
    type: string
    lifetime: user
    send_in_pings:
      - glean_internal_info
    description: |
      A running counter of the number of times pings of this type have been sent
    bugs:
      - https://bugzilla.mozilla.org/show_bug.cgi?id=1556964
    data_reviews:
      - https://bugzilla.mozilla.org/show_bug.cgi?id=1512938#c3
    data_sensitivity:
      - technical
    notification_emails:
      - glean-team@mozilla.com
    expires: never

  experiments:
    type: string  # It's not, but we don't have a way to specify its type
    lifetime: application
    send_in_pings:
      - glean_internal_info
    description: |
      Optional. A dictionary of active experiments.
    bugs:
      - https://bugzilla.mozilla.org/show_bug.cgi?id=1552471
    data_reviews:
      - https://bugzilla.mozilla.org/show_bug.cgi?id=1512938#c3
    data_sensitivity:
      - technical
    notification_emails:
      - glean-team@mozilla.com
    expires: never

  start_time:
    type: datetime
    lifetime: user
    send_in_pings:
      - glean_internal_info
    description: |
      The time of the start of collection of the data in the ping,
      in local time and with minute precision, including timezone information.
    bugs:
      - https://bugzilla.mozilla.org/show_bug.cgi?id=1556966
    data_reviews:
      - https://bugzilla.mozilla.org/show_bug.cgi?id=1512938#c3
    data_sensitivity:
      - technical
    notification_emails:
      - glean-team@mozilla.com
    expires: never

  end_time:
    type: datetime
    lifetime: ping
    send_in_pings:
      - glean_internal_info
    description: |
      The time of the end of collection of the data in the ping,
      in local time and with minute precision, including timezone information.
      This is also the time this ping was generated
      and is likely well before ping transmission time.
    bugs:
      - https://bugzilla.mozilla.org/show_bug.cgi?id=1556966
    data_reviews:
      - https://bugzilla.mozilla.org/show_bug.cgi?id=1512938#c3
    data_sensitivity:
      - technical
    notification_emails:
      - glean-team@mozilla.com
    expires: never

  reason:
    type: string
    lifetime: ping
    send_in_pings:
      - glean_internal_info
    description: |
      The optional reason the ping was submitted.
      The specific values for reason are specific to each ping, and are
      documented in the ping's pings.yaml file.
    bugs:
      - https://bugzilla.mozilla.org/show_bug.cgi?id=1557048
    data_reviews:
      - https://bugzilla.mozilla.org/show_bug.cgi?id=1609218#c4
    data_sensitivity:
      - technical
    notification_emails:
      - glean-team@mozilla.com
    expires: never

glean.error:
  invalid_value:
    type: labeled_counter
    description: |
      Counts the number of times a metric was set to an invalid value.
      The labels are the `category.name` identifier of the metric.
    bugs:
      - https://bugzilla.mozilla.org/1499761
    data_reviews:
      - https://bugzilla.mozilla.org/show_bug.cgi?id=1499761#c5
    data_sensitivity:
      - technical
    notification_emails:
      - glean-team@mozilla.com
    expires: never
    send_in_pings:
      - all-pings
    no_lint:
      - COMMON_PREFIX

  invalid_label:
    type: labeled_counter
    description: |
      Counts the number of times a metric was set with an invalid label.
      The labels are the `category.name` identifier of the metric.
    bugs:
      - https://bugzilla.mozilla.org/1499761
    data_reviews:
      - https://bugzilla.mozilla.org/show_bug.cgi?id=1499761#c5
    data_sensitivity:
      - technical
    notification_emails:
      - glean-team@mozilla.com
    expires: never
    send_in_pings:
      - all-pings
    no_lint:
      - COMMON_PREFIX

  invalid_state:
    type: labeled_counter
    description: |
      Counts the number of times a timing metric was used incorrectly.
      The labels are the `category.name` identifier of the metric.
    bugs:
      - https://bugzilla.mozilla.org/1566380
    data_reviews:
      - https://bugzilla.mozilla.org/show_bug.cgi?id=1499761#c5
    data_sensitivity:
      - technical
    notification_emails:
      - glean-team@mozilla.com
    expires: never
    send_in_pings:
      - all-pings
    no_lint:
      - COMMON_PREFIX

  invalid_overflow:
    type: labeled_counter
    description: |
      Counts the number of times a metric was set a value that overflowed.
      The labels are the `category.name` identifier of the metric.
    bugs:
      - https://bugzilla.mozilla.org/show_bug.cgi?id=1591912
    data_reviews:
      - https://bugzilla.mozilla.org/show_bug.cgi?id=1591912#c3
    data_sensitivity:
      - technical
    notification_emails:
      - glean-team@mozilla.com
    expires: never
    send_in_pings:
      - all-pings
    no_lint:
      - COMMON_PREFIX

  preinit_tasks_overflow:
    type: counter
    description: |
      The number of tasks queued in the pre-initialization buffer.
      Only sent if the buffer overflows.
    unit:
      tasks
    bugs:
      - https://bugzilla.mozilla.org/show_bug.cgi?id=1609482
    data_reviews:
      - https://bugzilla.mozilla.org/show_bug.cgi?id=1609482#c3
    data_sensitivity:
      - technical
    notification_emails:
      - glean-team@mozilla.com
    expires: never
    no_lint:
      - COMMON_PREFIX

  io:
    type: counter
    description: |
      The number of times we encountered an IO error
      when writing a pending ping to disk.
    bugs:
      - https://bugzilla.mozilla.org/show_bug.cgi?id=1686233
    data_reviews:
      - https://bugzilla.mozilla.org/show_bug.cgi?id=1686233#c2
    data_sensitivity:
      - technical
    notification_emails:
      - glean-team@mozilla.com
      - jrediger@mozilla.com
    expires: never

glean.upload:
  ping_upload_failure:
    type: labeled_counter
    description: |
      Counts the number of ping upload failures, by type of failure.
      This includes failures for all ping types,
      though the counts appear in the next successfully sent `metrics` ping.
    labels:
      - "status_code_4xx"
      - "status_code_5xx"
      - "status_code_unknown"
      - "unrecoverable"
      - "recoverable"
    bugs:
      - https://bugzilla.mozilla.org/show_bug.cgi?id=1589124
    data_reviews:
      - https://bugzilla.mozilla.org/show_bug.cgi?id=1589124#c1
    data_sensitivity:
      - technical
    notification_emails:
      - glean-team@mozilla.com
    expires: never
    no_lint:
      - COMMON_PREFIX

  discarded_exceeding_pings_size:
    type: memory_distribution
    description: |
      The size of pings that exceeded the maximum ping size allowed for upload.
    memory_unit: kilobyte
    bugs:
      - https://bugzilla.mozilla.org/show_bug.cgi?id=1597761
    data_reviews:
      - https://bugzilla.mozilla.org/show_bug.cgi?id=1597761#c10
    data_sensitivity:
      - technical
    notification_emails:
      - glean-team@mozilla.com
    expires: never
    no_lint:
      - COMMON_PREFIX

  pending_pings_directory_size:
    type: memory_distribution
    description: |
      The size of the pending pings directory upon initialization of Glean.
      This does not include the size of the deletion request pings directory.
    memory_unit: kilobyte
    bugs:
      - https://bugzilla.mozilla.org/show_bug.cgi?id=1601550
    data_reviews:
      - https://bugzilla.mozilla.org/show_bug.cgi?id=1601550#c3
    data_sensitivity:
      - technical
    notification_emails:
      - glean-team@mozilla.com
    expires: never
    no_lint:
      - COMMON_PREFIX

  deleted_pings_after_quota_hit:
    type: counter
    description: |
      The number of pings deleted after the quota
      for the size of the pending pings directory or number of files is hit.
      Since quota is only calculated for the pending pings directory,
      and deletion request ping live in a different directory,
      deletion request pings are never deleted.
    bugs:
      - https://bugzilla.mozilla.org/show_bug.cgi?id=1601550
    data_reviews:
      - https://bugzilla.mozilla.org/show_bug.cgi?id=1601550#c3
    data_sensitivity:
      - technical
    notification_emails:
      - glean-team@mozilla.com
    expires: never
    no_lint:
      - COMMON_PREFIX

  pending_pings:
    type: counter
    description: |
      The total number of pending pings at startup.
      This does not include deletion-request pings.
    bugs:
      - https://bugzilla.mozilla.org/show_bug.cgi?id=1665041
    data_reviews:
      - https://bugzilla.mozilla.org/show_bug.cgi?id=1665041#c23
    data_sensitivity:
      - technical
    notification_emails:
      - glean-team@mozilla.com
      - jrediger@mozilla.com
    expires: never
    no_lint:
      - COMMON_PREFIX

glean.database:
  size:
    type: memory_distribution
    description: |
      The size of the database file at startup.
    memory_unit: byte
    bugs:
      - https://bugzilla.mozilla.org/show_bug.cgi?id=1656589
    data_reviews:
      - https://bugzilla.mozilla.org/show_bug.cgi?id=1656589#c7
    data_sensitivity:
      - technical
    notification_emails:
      - glean-team@mozilla.com
    expires: never

glean.validation:
  first_run_hour:
    no_lint:
      - UNIT_IN_NAME
    type: datetime
    lifetime: user
    send_in_pings:
      - metrics
      - baseline
    time_unit: hour
    description: |
      The hour of the first run of the application.
    bugs:
      - https://bugzilla.mozilla.org/1680783
    data_reviews:
      - https://bugzilla.mozilla.org/show_bug.cgi?id=1680783#c5
    data_sensitivity:
      - technical
    notification_emails:
      - glean-team@mozilla.com
    expires:
      never
  foreground_count:
    type: counter
    description: |
      On mobile, the number of times the application went to foreground.
    bugs:
      - https://bugzilla.mozilla.org/show_bug.cgi?id=1683707
      - https://bugzilla.mozilla.org/show_bug.cgi?id=1685712
    data_reviews:
      - https://bugzilla.mozilla.org/show_bug.cgi?id=1683707#c2
    data_sensitivity:
      - technical
    notification_emails:
      - glean-team@mozilla.com
    expires:
      never
  pings_submitted:
    type: labeled_counter
    description: |
      A count of the pings submitted, by ping type.

      This metric appears in both the metrics and baseline pings.

      - On the metrics ping, the counts include the number of pings sent since
        the last metrics ping (including the last metrics ping)
      - On the baseline ping, the counts include the number of pings send since
        the last baseline ping (including the last baseline ping)
    send_in_pings:
      - metrics
      - baseline
    bugs:
      - https://bugzilla.mozilla.org/show_bug.cgi?id=1586764
    data_reviews:
      - https://bugzilla.mozilla.org/show_bug.cgi?id=1586764#c3
    data_sensitivity:
      - technical
    notification_emails:
      - glean-team@mozilla.com
    expires:
      never

glean.time:
  invalid_timezone_offset:
    type: counter
    description: |
      Counts the number of times we encountered an invalid timezone offset
      when trying to get the current time.
      A timezone offset is invalid if it is outside [-24h, +24h].
      If invalid a UTC offset is used (+0h).
    lifetime: ping
    send_in_pings:
      - metrics
    bugs:
      - https://bugzilla.mozilla.org/show_bug.cgi?id=1611770
    data_reviews:
      - https://bugzilla.mozilla.org/show_bug.cgi?id=1611770#c9
    data_sensitivity:
      - technical
    notification_emails:
      - jrediger@mozilla.com
      - glean-team@mozilla.com
    expires: 2021-06-30