# 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/.

# Adding a new metric? We have docs for that!
# https://firefox-source-docs.mozilla.org/toolkit/components/glean/user/new_definitions_file.html

---
$schema: moz://mozilla.org/schemas/glean/metrics/2-0-0
$tags:
  - 'Core :: Storage: Quota Manager'

dom.quota.try:
  error_step:
    type: event
    description: >
      An event recorded on an error of the quota manager or its clients.
      Since errors are usually propagated up the call chain, all such
      propagation steps are recorded for an error. This is only active
      during specific contexts, in particular during storage
      initialization. No dynamic data is included in the event beyond the
      error code which will be added through Bug 1670555.
      This event was generated to correspond to the Legacy Telemetry event
      dom.quota.try.error#step.
    bugs:
      - https://bugzil.la/1665088
    data_reviews:
      - https://bugzil.la/1665088
    notification_emails:
      - jan.varga@gmail.com
      - storage-telemetry@mozilla.com
    expires: never
    extra_keys:
      context:
        description: >
          The context in which the error occurred, e.g. during a storage initialization.
          Telemetry events are only emitted for selected contexts.
        type: string
      frame_id:
        description: >
          Optionally, the frame within stack_id.
        type: string
      process_id:
        description: >
          Optionally, the process in which the error occured.
        type: string
      result:
        description: >
          Optionally, the name of the error that occurred.
        type: string
      seq:
        description: >
          Sequence number.
        type: quantity
      severity:
        description: >
          One of WARNING or ERROR.
        type: string
      source_file:
        description: >
          The name of the source code file where the error occurred.
        type: string
      source_line:
        description: >
          The line within source_file where the error occurred.
        type: quantity
      stack_id:
        description: >
          Optionally, the stack within process_id.
        type: string
    telemetry_mirror: DomQuotaTry_Error_Step
quotamanager:
  restore_origin_directory_metadata_counter:
    type: counter
    description: >
      Increments each time QuotaManager::RestoreDirectoryMetadata2 is called to
      restore origin directory metadata. This typically occurs when expected
      directory metadata is missing or needs to be regenerated. The counter is
      incremented regardless of whether the restoration ultimately succeeds or
      fails.
      This can provide insight into the impacts of specific code changes,
      including potential optimizations or regressions.
    bugs:
      - https://bugzilla.mozilla.org/show_bug.cgi?id=1961884
    data_reviews:
      - https://bugzilla.mozilla.org/show_bug.cgi?id=1961884
    data_sensitivity:
      - technical
    notification_emails:
      - jan.varga@gmail.com
      - storage-telemetry@mozilla.com
    expires: never
quotamanager.initialize.repository:
  number_of_iterations:
    type: labeled_custom_distribution
    description: >
      This metric logs the count of directory entries iterated within the
      QuotaManager::InitializeRepository function for each repository type.
      Each instance of this metric is labeled with one of three repository
      types: "persistent", "temporary" or "default" (there's also "private"
      repository but that should never be iterated by the function).
      The main purpose is to track and analyze iteration counts during the
      initialization process of each repository type, helping to identify
      performance trends or potential inefficiencies across these repositories.
      This can provide insight into the impacts of specific code changes,
      including potential optimizations or regressions.
    range_min: 0
    range_max: 65535
    bucket_count: 50
    histogram_type: exponential
    unit: integer
    bugs:
      - https://bugzilla.mozilla.org/show_bug.cgi?id=1927260
    data_reviews:
      - https://bugzilla.mozilla.org/show_bug.cgi?id=1927260
    data_sensitivity:
      - technical
    notification_emails:
      - jan.varga@gmail.com
      - storage-telemetry@mozilla.com
    expires: never
    labels:
      - persistent
      - temporary
      - default
      - private
quotamanager.initialize.temporarystorage:
  total_time_excluding_suspend:
    type: timing_distribution
    time_unit: millisecond
    description: >
      This metric logs the total time required to initialize temporary storage
      within the QuotaManager after startup on the I/O thread. The duration
      excludes any periods when the system was suspended (e.g. system sleep or
      hibernation), to better reflect actual time spent performing temporary
      storage initialization.
      The primary goal is to measure the actual runtime cost of temporary
      storage initialization under typical conditions, without distortion from
      system-level suspension delays.
      This data can help detect performance regressions or improvements during
      startup-related phases, particularly for users with significant amounts
      of temporary storage data on disk.
    bugs:
      - https://bugzilla.mozilla.org/show_bug.cgi?id=1955992
    data_reviews:
      - https://bugzilla.mozilla.org/show_bug.cgi?id=1955992
    data_sensitivity:
      - technical
    notification_emails:
      - jan.varga@gmail.com
      - storage-telemetry@mozilla.com
    expires: never
  non_persisted_zero_usage_origins:
    type: custom_distribution
    description: >
      Logs the number of non-persisted origins that have zero quota-charged
      usage after full temporary storage initialization. These origins do not
      store any real data but still contribute to internal bookkeeping by
      having directories and files created on disk, which can unnecessarily
      increase initialization costs. Measuring how many such origins exist in
      the wild helps evaluate whether the temporary storage cleanup logic
      should be updated to clear them. This in turn can guide potential
      optimizations and improve the performance of temporary storage
      initialization over time, while also helping to detect unexpected
      regressions.
      Note: Non-persisted origins can be cleared when they have no data, while
      persisted origins cannot be cleared even at zero usage because the
      persisted flag is currently stored alongside the origin data and would be
      lost.
    range_min: 0
    range_max: 65535
    bucket_count: 50
    histogram_type: exponential
    unit: integer
    bugs:
      - https://bugzilla.mozilla.org/show_bug.cgi?id=1975258
    data_reviews:
      - https://bugzilla.mozilla.org/show_bug.cgi?id=1975258
    data_sensitivity:
      - technical
    notification_emails:
      - jan.varga@gmail.com
      - storage-telemetry@mozilla.com
    expires: never
quotamanager.shutdown:
  total_time_excluding_suspend:
    type: timing_distribution
    time_unit: millisecond
    description: >
      This metric logs the total time required to shut down the QuotaManager
      instance on the PBackground thread. The duration excludes any periods
      when the system was suspended (system sleep or hibernation), to better
      reflect actual time spent performing shutdown.
      While the shutdown process is measured on the PBackground thread, it
      involves spinning the event loop and thus waiting for operations on other
      threads (especially I/O threads) to complete.
      The primary goal is to measure the actual runtime cost of shutdown under
      typical conditions, without distortion from system-level suspension
      delays.
      This data can help detect performance regressions or improvements related
      to QuotaManager shutdown behavior, especially in scenarios involving
      large amounts of user storage data.
    bugs:
      - https://bugzilla.mozilla.org/show_bug.cgi?id=1590635
    data_reviews:
      - https://bugzilla.mozilla.org/show_bug.cgi?id=1590635
    data_sensitivity:
      - technical
    notification_emails:
      - jan.varga@gmail.com
      - storage-telemetry@mozilla.com
    expires: never

dom.quota:
  info_load_time:
    type: labeled_timing_distribution
    description: >
      Time (ms) for the QuotaManager to load quota information. Keyed by
      conditions during quota info loading, see RecordTimeDeltaHelper::Run in
      https://searchfox.org/firefox-main/source/dom/quota/ActorsParent.cpp

      This metric was generated to correspond to the Legacy Telemetry
      exponential histogram QM_QUOTA_INFO_LOAD_TIME_V0.
    time_unit: millisecond
    bugs:
      - https://bugzilla.mozilla.org/show_bug.cgi?id=1609625
      - https://bugzilla.mozilla.org/show_bug.cgi?id=1683102
    data_reviews:
      - https://bugzilla.mozilla.org/show_bug.cgi?id=1609625
      - https://bugzilla.mozilla.org/show_bug.cgi?id=1683102
    notification_emails:
      - jan.varga@gmail.com
      - storage-telemetry@mozilla.com
    expires: never
    telemetry_mirror: QM_QUOTA_INFO_LOAD_TIME_V0

  shutdown_time:
    type: labeled_timing_distribution
    description: >
      Time (ms) for the QuotaManager to shutdown. Keyed by conditions during
      shutdown, see RecordTimeDeltaHelper::Run in
      https://searchfox.org/firefox-main/source/dom/quota/ActorsParent.cpp

      This metric was generated to correspond to the Legacy Telemetry
      exponential histogram QM_SHUTDOWN_TIME_V0.
    time_unit: millisecond
    bugs:
      - https://bugzilla.mozilla.org/show_bug.cgi?id=1824075
    data_reviews:
      - https://bugzilla.mozilla.org/show_bug.cgi?id=1824075
    notification_emails:
      - jan.varga@gmail.com
      - storage-telemetry@mozilla.com
    expires: never
    telemetry_mirror: QM_SHUTDOWN_TIME_V0

  first_initialization_attempt:
    type: dual_labeled_counter
    description: >
      True if the first initialization attempt succeeded, keyed by the
      initialization type.

      This metric was generated to correspond to the Legacy Telemetry boolean
      histogram QM_FIRST_INITIALIZATION_ATTEMPT.
    dual_labels:
      key:
        description: No static keys unfortunately.
      category:
        labels:
          - "false"
          - "true"
        description: Boolean
    bugs:
      - https://bugzilla.mozilla.org/show_bug.cgi?id=1592934
    data_reviews:
      - https://bugzilla.mozilla.org/show_bug.cgi?id=1592934
    notification_emails:
      - jan.varga@gmail.com
      - storage-telemetry@mozilla.com
    expires: never
    telemetry_mirror: QM_FIRST_INITIALIZATION_ATTEMPT
