<!--
Copyright 2020 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 Subresource 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>

<histogram name="SubresourceFilter.Actions2" enum="SubresourceFilterActions2"
    expires_after="2027-01-31">
  <owner>alexmt@chromium.org</owner>
  <owner>chrome-ads-histograms@google.com</owner>
  <summary>
    Counts of various UI and user action events related to the
    SubresourceFilter. This will be triggered when portions of the UI are shown
    or interacted with.
  </summary>
</histogram>

<histogram name="SubresourceFilter.DocumentLoad.RulesetIsAvailable"
    enum="BooleanAvailable" expires_after="2027-01-03">
  <owner>alexmt@chromium.org</owner>
  <owner>chrome-ads-histograms@google.com</owner>
  <summary>
    Whenever a document load is committed in any frame and subresource filtering
    should be activated, records whether the filtering rules are available.

    Warning: This metric expired after M77 (around 09/2019) and was unexpired in
    07/2023. Data may be missing.
  </summary>
</histogram>

<histogram name="SubresourceFilter.DocumentLoad.SubframeFilteringDelay.Allowed"
    units="microseconds" expires_after="2027-02-07">
  <owner>alexmt@chromium.org</owner>
  <owner>chrome-ads-histograms@google.com</owner>
  <summary>
    Records the total time a child frame navigation was delayed while
    calculating whether it should be disallowed or not. Logged for all
    navigations that were allowed.

    This metric uses UMA_HISTOGRAM_CUSTOM_MICROSECONDS_TIMES to acccount for
    clients with low-resolution clocks.
  </summary>
</histogram>

<histogram
    name="SubresourceFilter.DocumentLoad.SubframeFilteringDelay.Disallowed2"
    units="microseconds" expires_after="2027-01-03">
  <owner>alexmt@chromium.org</owner>
  <owner>chrome-ads-histograms@google.com</owner>
  <summary>
    Records the total time a child frame navigation was delayed while
    calculating whether it should be disallowed or not. Logged for all
    navigations with the disallowed load policy.

    This metric uses UMA_HISTOGRAM_CUSTOM_MICROSECONDS_TIMES to acccount for
    clients with low-resolution clocks.
  </summary>
</histogram>

<histogram
    name="SubresourceFilter.DocumentLoad.SubframeFilteringDelay.WouldDisallow"
    units="microseconds" expires_after="2027-01-03">
  <owner>alexmt@chromium.org</owner>
  <owner>chrome-ads-histograms@google.com</owner>
  <summary>
    Records the total time a child frame navigation was delayed while
    calculating whether it should be disallowed or not. Logged for all
    navigations with the would_disallow load policy.

    This metric uses UMA_HISTOGRAM_CUSTOM_MICROSECONDS_TIMES to acccount for
    clients with low-resolution clocks.
  </summary>
</histogram>

<histogram name="SubresourceFilter.IndexRuleset.CPUDuration" units="ms"
    expires_after="2026-09-15">
  <owner>jkarlin@chromium.org</owner>
  <owner>chrome-ads-histograms@google.com</owner>
  <summary>
    The total CPU time it took to parse and index all rules. Does not include
    time when the indexing thread was not doing actual work, e.g. waiting for
    I/O or being descheduled. Recorded every time the RulesetService kicks off a
    ruleset indexing process.

    Warning: This metric expired around 02/2020 and was unexpired 07/2023. Data
    may be missing.
  </summary>
</histogram>

<histogram name="SubresourceFilter.IndexRuleset.NumUnsupportedRules"
    units="rules" expires_after="2026-09-15">
  <owner>jkarlin@chromium.org</owner>
  <owner>chrome-ads-histograms@google.com</owner>
  <summary>
    The number of rules that could be not be successfully indexed and therefore
    have been ignored. Recorded every time the RulesetService kicks off a
    ruleset indexing process and it reaches the point where rules are getting
    indexed. This is logged when a new ruleset is indexed for the first time on
    Chrome start.

    Warning: This metric expired after M90 (around 05/2021) and was unexpired
    09/2021. It expired again 09/2022 and was unexpired 07/2023. Data may be
    missing.
  </summary>
</histogram>

<histogram name="SubresourceFilter.IndexRuleset.Verify.Status"
    enum="SubresourceFilterVerifyStatus" expires_after="2027-02-21">
  <owner>alexmt@chromium.org</owner>
  <owner>chrome-ads-histograms@google.com</owner>
  <summary>
    The result of the IndexRulesetMatcher Verify method. Either pass if both the
    checksum and verifier succeeded, or a value indicating which combination of
    them failed. Note that a zero checksum indicates that the checksum has not
    yet been stored during indexing (for rulesets indexed prior to the
    checksumming code). This is logged when the indexed ruleset is loaded on
    Chrome start.
  </summary>
</histogram>

<histogram name="SubresourceFilter.IndexRuleset.Verify2.WallDuration"
    units="ms" expires_after="2027-01-17">
  <owner>alexmt@chromium.org</owner>
  <owner>chrome-ads-histograms@google.com</owner>
  <summary>
    The total time it took to verify the indexed ruleset in the browser process.
    Logged every time verification occurs, which usually occurs when the first
    page with activation is navigated to. This is logged when the indexed
    ruleset is loaded on Chrome start.
  </summary>
</histogram>

<histogram name="SubresourceFilter.IndexRuleset.WallDuration" units="ms"
    expires_after="2026-11-01">
  <owner>jkarlin@chromium.org</owner>
  <owner>chrome-ads-histograms@google.com</owner>
  <summary>
    The total time it took to read and index all rules. Includes I/O time for
    reading the unindexed rules, but not for writing the indexed ruleset.
    Recorded every time the RulesetService kicks off a ruleset indexing process.

    Warning: Data is incomplete. This histogram expired in 08/2023 and was
    unexpired in 12/2023.
  </summary>
</histogram>

<histogram
    name="SubresourceFilter.MainFrameLoad.RulesetIsAvailableAnyActivationLevel"
    enum="BooleanAvailable" expires_after="2027-01-17">
  <owner>alexmt@chromium.org</owner>
  <owner>jkarlin@chromium.org</owner>
  <summary>
    Whenever a document load is committed in the root frame, records whether the
    filtering rules are available. This is independent of whether or not
    subresource filtering should be activated.
  </summary>
</histogram>

<histogram name="SubresourceFilter.PageLoad.ActivationDecision"
    enum="SubresourceFilterActivationDecision" expires_after="2027-01-17">
  <owner>jkarlin@chromium.org</owner>
  <owner>chrome-ads-histograms@google.com</owner>
  <summary>
    Records the policy decision to activate subresource filtering for a page
    load. 'Activated' indicates that subresource filtering was activated. All
    other reasons indicate that subresource filtering was not activated.

    Warning: This metric expired around 08/2021 and was unexpired 07/2023. Data
    may be missing.
  </summary>
</histogram>

<histogram name="SubresourceFilter.PageLoad.ActivationList"
    enum="ActivationList" expires_after="2027-01-31">
  <owner>alexmt@chromium.org</owner>
  <owner>chrome-ads-histograms@google.com</owner>
  <summary>
    The ActivationList or NONE that the root frame's navigation matched with.
    Recorded at WillProcessResponse time for an outermost main frame navigation.
  </summary>
</histogram>

<histogram name="SubresourceFilter.PageLoad.ActivationState"
    enum="SubresourceFilterActivationState" expires_after="2027-01-31">
  <owner>alexmt@chromium.org</owner>
  <owner>chrome-ads-histograms@google.com</owner>
  <summary>
    Whenever a navigation finishes in a root frame, records whether subresource
    filtering should be activated for that load.
  </summary>
</histogram>

<histogram name="SubresourceFilter.PageLoad.ActivationState.DidInherit"
    enum="SubresourceFilterActivationState" expires_after="2022-11-02">
  <owner>alexmt@chromium.org</owner>
  <owner>chrome-ads-histograms@google.com</owner>
  <summary>
    Whenever a navigation finishes in a root frame that inherits from its
    same-origin opener, records whether subresource filtering should be
    activated for that load.
  </summary>
</histogram>

<histogram name="SubresourceFilter.PageLoad.ActivationState.DisabledReason"
    enum="SubresourceFilterDisabledReason" expires_after="2027-01-03">
  <owner>yaoxia@chromium.org</owner>
  <owner>chrome-ads-histograms@google.com</owner>
  <summary>
    Whenever a navigation finishes in a root frame, and when subresource
    filtering should be disabled for that load, record the disabled reason.
  </summary>
</histogram>

<histogram name="SubresourceFilter.PageLoad.AdsInterventionTriggered"
    enum="AdsViolations" expires_after="2027-02-07">
  <owner>yaoxia@google.com</owner>
  <owner>chrome-ads-histograms@google.com</owner>
  <summary>
    Records that an ads violation has been triggered on a page load. Logged at
    the time the ads violation is detected.

    Warning: This metric expired after M90 (around 05/2021) and was unexpired
    07/2023. Data may be missing.
  </summary>
</histogram>

<histogram name="SubresourceFilter.PageLoad.NumSubresourceLoads.Disallowed"
    units="resource loads" expires_after="2027-02-07">
  <owner>jkarlin@chromium.org</owner>
  <owner>chrome-ads-histograms@google.com</owner>
  <summary>
    Whenever a page load is finished with subresource filtering activated,
    records the total number of subresource loads that have been disallowed.
    This only differs from `MatchedRules` when filtering is performed in dry-run
    mode.

    Warning: This metric expired around 08/2021 and was unexpired 07/2023. Data
    may be missing.
  </summary>
</histogram>

<histogram name="SubresourceFilter.PageLoad.NumSubresourceLoads.Evaluated"
    units="resource loads" expires_after="2026-09-15">
  <owner>jkarlin@chromium.org</owner>
  <owner>chrome-ads-histograms@google.com</owner>
  <summary>
    Whenever a page load is finished with subresource filtering activated,
    records the total number of subresource loads that have been evaluated. This
    only differs from 'Total' when some of subdocuments is subject to a
    deactivating rule with DOCUMENT activation type.
  </summary>
</histogram>

<histogram name="SubresourceFilter.PageLoad.NumSubresourceLoads.MatchedRules"
    units="resource loads" expires_after="2026-11-15">
  <owner>jkarlin@chromium.org</owner>
  <owner>chrome-ads-histograms@google.com</owner>
  <summary>
    Whenever a page load is finished with subresource filtering activated,
    records the total number of subresource loads that have matched filtering
    rules. This only differs from `Disallowed` when filtering is performed in
    dry-run mode.
  </summary>
</histogram>

<histogram name="SubresourceFilter.PageLoad.NumSubresourceLoads.Total"
    units="resource loads" expires_after="2026-09-15">
  <owner>jkarlin@chromium.org</owner>
  <owner>chrome-ads-histograms@google.com</owner>
  <summary>
    Whenever a page load is finished with subresource filtering activated,
    records the total number of subresource loads that have gone through the
    subresource filtering pipeline.
  </summary>
</histogram>

<histogram name="SubresourceFilter.PageLoad.SafeBrowsingDelay" units="ms"
    expires_after="2026-12-27">
  <owner>alexmt@chromium.org</owner>
  <owner>chrome-ads-histograms@google.com</owner>
  <summary>
    The navigation delay imposed by the subresource filter on a given navigation
    due to Safe Browsing checks.

    This metric expired after M83 and was renewed in M88, so it has incomplete
    data between M84 and M87 inclusively.
  </summary>
</histogram>

<histogram
    name="SubresourceFilter.PageLoad.SubresourceEvaluation.TotalCPUDuration"
    units="microseconds" expires_after="2027-02-14">
  <owner>alexmt@chromium.org</owner>
  <owner>chrome-ads-histograms@google.com</owner>
  <summary>
    Whenever a page load is finished with subresource filtering activated,
    records the total thread CPU time spent on evaluating subresource requests,
    aggregated across all frames.

    Note: this histogram is emitted for all clients, both ones which have
    high-resolution timer available and those which don't.

    Warning: This metric expired after 01/2020 and was unexpired 07/2021. Data
    may be missing.
  </summary>
</histogram>

<histogram
    name="SubresourceFilter.PageLoad.SubresourceEvaluation.TotalWallDuration"
    units="microseconds" expires_after="2027-02-07">
  <owner>alexmt@chromium.org</owner>
  <owner>chrome-ads-histograms@google.com</owner>
  <summary>
    Whenever a page load is finished with subresource filtering activated,
    records the total real time spent on evaluating subresource requests,
    aggregated across all frames. This includes the time spent on waiting or
    being descheduled.

    Note: this histogram is emitted for all clients, both ones which have
    high-resolution timer available and those which don't.

    Warning: This metric expired after M78 and was unexpired 07/2021. Data may
    be missing.
  </summary>
</histogram>

<histogram name="SubresourceFilter.SafeBrowsing.TotalCheckTime" units="ms"
    expires_after="2027-02-21">
  <owner>alexmt@chromium.org</owner>
  <owner>chrome-ads-histograms@google.com</owner>
  <summary>
    The time an individual Safe Browsing URL check took before finishing,
    including posting tasks to and from the IO thread. Measured on the UI thread
    on navigation.

    This metric expired after M83 and was renewed in M88, so it has incomplete
    data between M84 and M87 inclusively.
  </summary>
</histogram>

<histogram name="SubresourceFilter.SubresourceLoad.Evaluation.CPUDuration"
    units="microseconds" expires_after="2026-12-27">
  <owner>alexmt@chromium.org</owner>
  <owner>chrome-ads-histograms@google.com</owner>
  <summary>
    Whenever a subresource of a document is evaluated against the ruleset,
    records the thread CPU time spent on calculating whether it should be
    allowed to load.

    Warning: This metric may include reports from clients with low-resolution
    clocks (i.e. on Windows, ref. |TimeTicks::IsHighResolution()|). Such reports
    will cause this metric to have an abnormal distribution. When considering
    revising this histogram, see UMA_HISTOGRAM_CUSTOM_MICROSECONDS_TIMES for the
    solution.

    Warning: This metric expired after 01/2020 and was unexpired 07/2021. Data
    may be missing.
  </summary>
</histogram>

<histogram name="SubresourceFilter.SubresourceLoad.Evaluation.WallDuration"
    units="microseconds" expires_after="2027-01-17">
  <owner>alexmt@chromium.org</owner>
  <owner>chrome-ads-histograms@google.com</owner>
  <summary>
    Whenever a subresource of a document is evaluated against the ruleset,
    records how much time was spent on calculating whether it should be allowed
    to load.

    Warning: This metric may include reports from clients with low-resolution
    clocks (i.e. on Windows, ref. |TimeTicks::IsHighResolution()|). Such reports
    will cause this metric to have an abnormal distribution. When considering
    revising this histogram, see UMA_HISTOGRAM_CUSTOM_MICROSECONDS_TIMES for the
    solution.

    Warning: This metric expired after M85 and was unexpired 07/2021. Data may
    be missing
  </summary>
</histogram>

<histogram
    name="SubresourceFilter.SubresourceLoad.Evaluation.WallDuration.FirstRun"
    units="microseconds" expires_after="2027-01-31">
  <owner>alexmt@chromium.org</owner>
  <owner>csharrison@chromium.org</owner>
  <owner>chrome-ads-histograms@google.com</owner>
  <summary>
    Whenever a subresource of a document is evaluated against the ruleset,
    records how much time was spent on calculating whether it should be allowed
    to load. This is only recorded on the first run of the ruleset service in a
    particular process.

    Warning: This metric may include reports from clients with low-resolution
    clocks (i.e. on Windows, ref. |TimeTicks::IsHighResolution()|). Such reports
    will cause this metric to have an abnormal distribution. When considering
    revising this histogram, see UMA_HISTOGRAM_CUSTOM_MICROSECONDS_TIMES for the
    solution.
  </summary>
</histogram>

<histogram name="SubresourceFilter.UrlPatternIndex.CorruptedIndexFields"
    enum="Boolean" expires_after="2027-03-14">
  <owner>csharrison@chromium.org</owner>
  <owner>engedy@chromium.org</owner>
  <summary>
    Recorded at most once per process (renderer or browser) when the
    UrlPatternIndex hash table or empty slot is unexpectedly null or empty at
    match time, despite passing validation at construction. This indicates that
    the underlying flatbuffer index data was likely corrupted after loading
    (e.g. due to mmap corruption). Always emitted as true.
  </summary>
</histogram>

<histogram name="SubresourceFilter.UrlPatternIndex.HashTableProbeExhausted"
    enum="Boolean" expires_after="2027-03-12">
  <owner>csharrison@chromium.org</owner>
  <owner>engedy@chromium.org</owner>
  <summary>
    Recorded at most once per process (renderer or browser) when a hash table
    probe in UrlPatternIndex exhausts all slots without finding a match or empty
    slot, indicating that the underlying flatbuffer index data is likely
    corrupted. Always emitted as true.
  </summary>
</histogram>

<histogram name="SubresourceFilter.WriteRuleset.Result"
    enum="SubresourceFilterWriteRulesetResult" expires_after="2027-01-17">
  <owner>alexmt@chromium.org</owner>
  <owner>chrome-ads-histograms@google.com</owner>
  <summary>
    Whether indexing a version of the ruleset and writing it to disk succeeded,
    or failed at a particular step. Recorded every time the RulesetService kicks
    off a ruleset indexing process.

    Warning: Data is incomplete. This metric expired in 08/2023 and was
    unexpired in 12/2023.
  </summary>
</histogram>

</histograms>

</histogram-configuration>
