<!--
Copyright 2025 The Chromium Authors
Use of this source code is governed by a BSD-style license that can be
found in the LICENSE file.
-->

<!--
This file is used to generate a comprehensive list of PersistentCache and
SandboxedVfs histograms along with a detailed description for each histogram.

For best practices on writing histogram descriptions, see
https://chromium.googlesource.com/chromium/src.git/+/HEAD/tools/metrics/histograms/README.md

Please follow the instructions in the OWNERS file in this directory to find a
reviewer. If no OWNERS file exists, please consider signing up at
go/reviewing-metrics (Googlers only), as all subdirectories are expected to
have an OWNERS file. As a last resort you can send the CL to
chromium-metrics-reviews@google.com.
-->

<histogram-configuration>

<histograms>

<!-- LINT.IfChange(Client) -->

<variants name="Client">
  <variant name="CodeCache"/>
  <variant name="ShaderCache"/>
</variants>

<!-- LINT.ThenChange(//components/persistent_cache/client.h:Client) -->

<variants name="FileType">
  <variant name="DbFile" summary="database file"/>
  <variant name="JournalFile" summary="journal file"/>
  <variant name="WalIndexFile" summary="wal-index file"/>
  <variant name="WalIndexFileReadOnly"
      summary="wal-index file (read-only handle)"/>
  <variant name="WalJournalFile" summary="write-ahead log file"/>
</variants>

<variants name="Mode">
  <variant name="ReadOnly" summary="read only"/>
  <variant name="ReadWrite" summary="read/write"/>
</variants>

<!-- LINT.IfChange(VfsClient) -->

<variants name="VfsClient">
  <variant name="CodeCache"/>
  <variant name="ShaderCache"/>
  <variant name="SharedCacheIsolated"/>
</variants>

<!-- LINT.ThenChange(//components/sqlite_vfs/client.h:VfsClient) -->

<histogram name="PersistentCache.BackendInitialize.{Mode}.{Client}"
    units="microseconds" expires_after="2027-02-14">
  <owner>grt@chromium.org</owner>
  <owner>catan-team@chromium.org</owner>
  <summary>
    Time it took to initialize a backend for the {Client} in {Mode} mode.
    Recorded every time a backend is successfully initialized.

    WARNING: This metric is not recorded on clients with low-resolution clocks,
    which means measurments are biased against a portion of the population on
    Windows. See Windows.HasHighResolutionTimeTicks for the affected sample.
  </summary>
</histogram>

<histogram name="PersistentCache.Find.{Mode}.{Client}" units="microseconds"
    expires_after="2027-02-07">
  <owner>grt@chromium.org</owner>
  <owner>catan-team@chromium.org</owner>
  <summary>
    Time it took to attempt to find an entry for the {Client} in {Mode} mode.
    Recorded for one out of every 100 operations.

    WARNING: This metric is not recorded on clients with low-resolution clocks,
    which means measurments are biased against a portion of the population on
    Windows. See Windows.HasHighResolutionTimeTicks for the affected sample.
  </summary>
</histogram>

<histogram name="PersistentCache.Insert.{Client}" units="microseconds"
    expires_after="2027-02-07">
  <owner>grt@chromium.org</owner>
  <owner>catan-team@chromium.org</owner>
  <summary>
    Time it took to attempt to insert an entry for the {Client}. Recorded for
    one out of every 100 operations.

    WARNING: This metric is not recorded on clients with low-resolution clocks,
    which means measurments are biased against a portion of the population on
    Windows. See Windows.HasHighResolutionTimeTicks for the affected sample.
  </summary>
</histogram>

<histogram name="PersistentCache.InsertSize.{Client}" units="bytes"
    expires_after="2027-02-14">
  <owner>grt@chromium.org</owner>
  <owner>catan-team@chromium.org</owner>
  <summary>
    Number of bytes in an entry inserted for the {Client}. Recorded for one out
    of every 100 successfull operations.
  </summary>
</histogram>

<histogram name="SandboxedVfs.GetFileSystemIdError.{VfsClient}"
    enum="PlatformFileError" expires_after="2027-05-01">
  <owner>grt@chromium.org</owner>
  <owner>catan-team@chromium.org</owner>
  <summary>
    Reports the error encountered when attempting to retrieve the physical file
    system ID for a sandboxed SQLite file set's main database file for the
    {VfsClient}.
  </summary>
</histogram>

<histogram name="SandboxedVfs.LockResult.{VfsClient}" enum="PlatformFileError"
    expires_after="2027-01-10">
  <owner>grt@chromium.org</owner>
  <owner>catan-team@chromium.org</owner>
  <summary>
    Reports the result of locking a sandboxed SQLite file set's primary database
    file when opened for use by only a single connection for the {VfsClient}.
  </summary>
</histogram>

<histogram name="SandboxedVfs.LockStateOnAbandon.{VfsClient}" enum="LockState"
    expires_after="2027-01-03">
  <owner>grt@chromium.org</owner>
  <owner>catan-team@chromium.org</owner>
  <summary>
    The state of the shared atomic lock at the moment a sandboxed SQLite file
    set is abandoned for the {VfsClient}. The lock being held on abandonment
    either causes loss of entries or copying overhead. This is not expected to
    be a common case and this metric should be monitored as such. Logged each
    time a file is abandoned.
  </summary>
</histogram>

<histogram name="SandboxedVfs.{FileType}.{Operation}.{VfsClient}"
    enum="PlatformFileError" expires_after="2027-01-10">
  <owner>grt@chromium.org</owner>
  <owner>catan-team@chromium.org</owner>
  <summary>
    Reports the result of {Operation} a sandboxed SQLite file set's {FileType}
    for the {VfsClient}.
  </summary>
  <token key="Operation">
    <variant name="CreateResult" summary="creating or opening"/>
    <variant name="DeleteResult" summary="deleting"/>
    <variant name="SetLengthResult" summary="truncating"/>
  </token>
</histogram>

</histograms>

</histogram-configuration>
