<!--
Copyright 2021 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 Prefetch 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>

<variants name="PrefetchProxyCanaryCheckerClient">
  <variant name="DNS" summary="DNS canary check"/>
  <variant name="TLS" summary="TLS canary check"/>
</variants>

<variants name="SpeculationEagerness">
  <variant name="Conservative" summary="Conservative"/>
  <variant name="Eager" summary="Eager"/>
  <variant name="Moderate" summary="Moderate"/>
</variants>

<histogram
    name="PrefetchProxy.AfterClick.BlockUntilHeadDuration.{WasServed}.{SpeculationEagerness}"
    units="ms" expires_after="2023-09-10">
  <owner>curranmax@chromium.org</owner>
  <owner>ryansturm@chromium.org</owner>
  <owner>spelchat@chromium.org</owner>
  <summary>
    If a prefetch request has started but the head of the prefetch response has
    not been received yet when a navigation to a URL that matches the prefetch,
    then the prefetch service will block until the head of the prefetch response
    is received and then decide to serve or not serve the prefetch.

    This histogram records the amount of time that the prefetch service blocked
    until the head of the prefetch response was received. This histogram is only
    recorded for prefetches that are {WasServed} and with an Eagerness of
    {SpeculationEagerness}.
  </summary>
  <token key="WasServed">
    <variant name="NotServed" summary="not served"/>
    <variant name="Served" summary="served"/>
  </token>
  <token key="SpeculationEagerness" variants="SpeculationEagerness"/>
</histogram>

<histogram
    name="PrefetchProxy.AfterClick.Mainframe.CookieCopyStartToInterceptorCheck"
    units="ms" expires_after="2024-04-25">
  <owner>curranmax@chromium.org</owner>
  <owner>ryansturm@chromium.org</owner>
  <owner>spelchat@chromium.org</owner>
  <summary>
    Cross-Origin prefetches requested via the Speculation Rules API are made in
    an isolated network context. When the prefetched link is navigated to, the
    cookies are copied from this isolated network context to the user's default
    network context.

    This histogram records the time from the start of the cookie copy to when
    the URL interceptor trying to serve the prefetch checks the status of the
    cookie copy.
  </summary>
</histogram>

<histogram name="PrefetchProxy.AfterClick.Mainframe.CookieCopyTime" units="ms"
    expires_after="2023-09-10">
  <owner>curranmax@chromium.org</owner>
  <owner>ryansturm@chromium.org</owner>
  <owner>spelchat@chromium.org</owner>
  <summary>
    Cross-Origin prefetches requested via the Speculation Rules API are made in
    an isolated network context. When the prefetched link is navigated to, the
    cookies are copied from this isolated network context to the user's default
    network context.

    This histogram records the time required to copy cookies from the isolated
    network context used for a prefetch to the user's default network context
    after a prefetched link is navigated to.
  </summary>
</histogram>

<histogram name="PrefetchProxy.AfterClick.Mainframe.CookieReadTime" units="ms"
    expires_after="2023-09-10">
  <owner>curranmax@chromium.org</owner>
  <owner>ryansturm@chromium.org</owner>
  <owner>spelchat@chromium.org</owner>
  <summary>
    Cross-Origin prefetches requested via the Speculation Rules API are made in
    an isolated network context. When the prefetched link is na vigated to, the
    cookies are copied from this isolated network context to the user's default
    network context.

    This histogram records the time required to read the cookies from the
    isolated network context used for a prefetch before being copied to the
    user's default network context after a prefetched link is navigated to. Note
    this does not include the time it takes to write the cookies to the default
    network context.
  </summary>
</histogram>

<histogram name="PrefetchProxy.AfterClick.Mainframe.CookieWaitTime" units="ms"
    expires_after="2023-09-10">
  <owner>curranmax@chromium.org</owner>
  <owner>ryansturm@chromium.org</owner>
  <owner>spelchat@chromium.org</owner>
  <summary>
    Records the amount of time that the navigation to a previously prefetched
    page was delayed because cookies had to be copied from the isolated cookie
    jar.

    This is only the amount of time in which the cookie copy process blocks
    intercepting the navigation. The overall time it takes for the cookie copy
    process is recorded to the
    &quot;PrefetchProxy.AfterClick.Mainframe.Cookie(Copy|Read|Write)Time&quot;
    histograms.
  </summary>
</histogram>

<histogram name="PrefetchProxy.AfterClick.Mainframe.CookieWriteTime" units="ms"
    expires_after="2023-09-10">
  <owner>curranmax@chromium.org</owner>
  <owner>ryansturm@chromium.org</owner>
  <owner>spelchat@chromium.org</owner>
  <summary>
    Cross-Origin prefetches requested via the Speculation Rules API are made in
    an isolated network context. When the prefetched link is na vigated to, the
    cookies are copied from this isolated network context to the user's default
    network context.

    This histogram records the time required to write cookies from the isolated
    network context used for a prefetch to the user's default network context
    after a prefetched link is navigated to. Note this does not include the time
    it takes to read the cookies from the isolated network context.
  </summary>
</histogram>

<histogram name="PrefetchProxy.AfterClick.RedirectChainSize" units="count"
    expires_after="2023-09-10">
  <owner>curranmax@chromium.org</owner>
  <owner>ryansturm@chromium.org</owner>
  <owner>spelchat@chromium.org</owner>
  <summary>
    The redirect chain size of a served prefetch. This histogram is recorded
    only for prefetches that are served for a navigation.
  </summary>
</histogram>

<histogram
    name="PrefetchProxy.AfterClick.WasBlockedUntilHeadWhenServing.{SpeculationEagerness}"
    enum="Boolean" expires_after="2023-09-10">
  <owner>curranmax@chromium.org</owner>
  <owner>ryansturm@chromium.org</owner>
  <owner>spelchat@chromium.org</owner>
  <summary>
    If a prefetch request has started but the head of the prefetch response has
    not been received yet when a navigation to a URL that matches the prefetch,
    then the prefetch service will block until the head of the prefetch response
    is received and then decide to serve or not serve the prefetch.

    This histogram records whether or not prefetch service will block or not for
    a prefetch. This histogram is only for prefetches with an Eagerness of
    {SpeculationEagerness}.
  </summary>
  <token key="SpeculationEagerness" variants="SpeculationEagerness"/>
</histogram>

<histogram name="PrefetchProxy.AfterClick.WasFullRedirectChainServed"
    enum="Boolean" expires_after="2023-09-10">
  <owner>curranmax@chromium.org</owner>
  <owner>ryansturm@chromium.org</owner>
  <owner>spelchat@chromium.org</owner>
  <summary>
    Whether the full redirect chain of a prefetch is served (true), or just part
    of the redirect was served (false). This histogram is only recorded when: 1)
    the prefetch had at least one redirect (i.e. the redirect chain is at least
    2), and 2) at least part of prefetch redirect chain is served.
  </summary>
</histogram>

<histogram
    name="PrefetchProxy.CanaryChecker.CacheEntryAge.{PrefetchProxyCanaryCheckerClient}"
    units="hours" expires_after="2024-04-25">
  <owner>curranmax@chromium.org</owner>
  <owner>chrome-brapp-loading@chromium.org</owner>
  <summary>
    How old a cached probe result was when it was used, in hours.
  </summary>
  <token key="PrefetchProxyCanaryCheckerClient"
      variants="PrefetchProxyCanaryCheckerClient"/>
</histogram>

<histogram
    name="PrefetchProxy.CanaryChecker.CacheLookupResult.{PrefetchProxyCanaryCheckerClient}"
    enum="CanaryCheckLookupResult" expires_after="2024-04-25">
  <owner>curranmax@chromium.org</owner>
  <owner>chrome-brapp-loading@google.com</owner>
  <summary>
    Records the status of canary check cache lookups. A sample is recorded every
    time Chrome attempts to use a resource prefetched using the prefetch proxy.
    Cache misses or cached failures result in filter probing the origin before
    the prefetched response can be used.
  </summary>
  <token key="PrefetchProxyCanaryCheckerClient"
      variants="PrefetchProxyCanaryCheckerClient"/>
</histogram>

<histogram
    name="PrefetchProxy.CanaryChecker.FinalState.{PrefetchProxyCanaryCheckerClient}"
    enum="BooleanSuccess" expires_after="2024-04-25">
  <owner>curranmax@chromium.org</owner>
  <owner>chrome-brapp-loading@chromium.org</owner>
  <summary>
    Records the end state of a probe just before it goes inactive. This happens
    when the prober succeeds, fails and has no more retries, or the delegate
    stops probing.
  </summary>
  <token key="PrefetchProxyCanaryCheckerClient"
      variants="PrefetchProxyCanaryCheckerClient"/>
</histogram>

<histogram
    name="PrefetchProxy.CanaryChecker.GenerateCacheKey.{PrefetchProxyCanaryCheckerClient}"
    units="ms" expires_after="2024-04-25">
  <owner>curranmax@chromium.org</owner>
  <owner>chrome-brapp-loading@chromium.org</owner>
  <summary>
    Records the amount of time spent generating a cache key for the availability
    prober. In particular, this tracks how much getNetworkOperator calls might
    be slowing down this method. See crbug.com/1266018 for more details.
  </summary>
  <token key="PrefetchProxyCanaryCheckerClient"
      variants="PrefetchProxyCanaryCheckerClient"/>
</histogram>

<histogram
    name="PrefetchProxy.CanaryChecker.NetError.{PrefetchProxyCanaryCheckerClient}"
    enum="NetErrorCodes" expires_after="2024-04-25">
  <owner>curranmax@chromium.org</owner>
  <owner>chrome-brapp-loading@chromium.org</owner>
  <summary>
    Records the net error of a completed or timed out probe. Note that if a HTTP
    response does not occur within the probe's TTL, when a sample will also be
    added to the ERR_TIMED_OUT bucket.
  </summary>
  <token key="PrefetchProxyCanaryCheckerClient"
      variants="PrefetchProxyCanaryCheckerClient"/>
</histogram>

<histogram
    name="PrefetchProxy.CanaryChecker.NumAttemptsBeforeSuccess.{PrefetchProxyCanaryCheckerClient}"
    units="count" expires_after="2024-04-25">
  <owner>curranmax@chromium.org</owner>
  <owner>chrome-brapp-loading@chromium.org</owner>
  <summary>
    Records the number of attempts that are made to achieve a successful canary
    check. This is recorded every time we make a canary check and the result is
    a success. In particular, this means this is no recorded when a result was
    already cached or when the check attempt fails after exhausting its retries.
    This metric is 1-based so if a probe succeeds the first time, a sample of 1
    will be recorded.
  </summary>
  <token key="PrefetchProxyCanaryCheckerClient"
      variants="PrefetchProxyCanaryCheckerClient"/>
</histogram>

<histogram
    name="PrefetchProxy.CanaryChecker.TimeUntilFailure.{PrefetchProxyCanaryCheckerClient}"
    units="ms" expires_after="2024-04-25">
  <owner>curranmax@chromium.org</owner>
  <owner>chrome-brapp-loading@chromium.org</owner>
  <summary>
    Records the amount of time spent working on a single probe attempt to get to
    a failed state. Recorded every time a probe fails.
  </summary>
  <token key="PrefetchProxyCanaryCheckerClient"
      variants="PrefetchProxyCanaryCheckerClient"/>
</histogram>

<histogram
    name="PrefetchProxy.CanaryChecker.TimeUntilSuccess.{PrefetchProxyCanaryCheckerClient}"
    units="ms" expires_after="2024-04-25">
  <owner>curranmax@chromium.org</owner>
  <owner>chrome-brapp-loading@chromium.org</owner>
  <summary>
    Records the amount of time spent working on a single probe attempt to get to
    a successful state. Recorded every time a probe succeeds.
  </summary>
  <token key="PrefetchProxyCanaryCheckerClient"
      variants="PrefetchProxyCanaryCheckerClient"/>
</histogram>

<histogram name="PrefetchProxy.Prefetch.ExistingPrefetchWithMatchingURL"
    units="Boolean" expires_after="2023-08-27">
  <owner>curranmax@chromium.org</owner>
  <owner>ryansturm@chromium.org</owner>
  <owner>spelchat@chromium.org</owner>
  <summary>
    Records whether or not there was an existing prefetch with a matching URL
    from a different referring document when a new prefetch is requested. This
    is recorded everytime a prefetch is requested.
  </summary>
</histogram>

<histogram name="PrefetchProxy.Prefetch.Mainframe.BodyLength" units="bytes"
    expires_after="2023-08-27">
  <owner>curranmax@chromium.org</owner>
  <owner>ryansturm@chromium.org</owner>
  <owner>spelchat@chromium.org</owner>
  <summary>
    Records the response body length as cached in memory encountered when
    isolated prefetching a mainframe HTML resource from the Google Search Result
    Page. Recorded for non-network error prefetches only.
  </summary>
</histogram>

<histogram name="PrefetchProxy.Prefetch.Mainframe.ConnectTime" units="ms"
    expires_after="2023-08-27">
  <owner>curranmax@chromium.org</owner>
  <owner>ryansturm@chromium.org</owner>
  <owner>spelchat@chromium.org</owner>
  <summary>
    Records the time taken to establish a socket connection when isolated
    prefetching a mainframe HTML resource from the Google Search Result Page.
    Recorded for non-network error prefetches only.
  </summary>
</histogram>

<histogram name="PrefetchProxy.Prefetch.Mainframe.CookiesToCopy" units="count"
    expires_after="2023-08-27">
  <owner>curranmax@chromium.org</owner>
  <owner>ryansturm@chromium.org</owner>
  <owner>spelchat@chromium.org</owner>
  <summary>
    Records the number of cookies that needed to be copied from the prefetch
    navigation to the user's profile after a prefetched link is navigated to.
  </summary>
</histogram>

<histogram name="PrefetchProxy.Prefetch.Mainframe.NetError"
    enum="NetErrorCodes" expires_after="2023-08-27">
  <owner>curranmax@chromium.org</owner>
  <owner>ryansturm@chromium.org</owner>
  <owner>spelchat@chromium.org</owner>
  <summary>
    Records the Net Error encountered when isolated prefetching a mainframe HTML
    resource from the Google Search Result Page. Recorded for every completed
    prefetch.
  </summary>
</histogram>

<histogram name="PrefetchProxy.Prefetch.Mainframe.RespCode"
    enum="HttpResponseCode" expires_after="2023-08-27">
  <owner>curranmax@chromium.org</owner>
  <owner>ryansturm@chromium.org</owner>
  <owner>spelchat@chromium.org</owner>
  <summary>
    Records the HTTP response code encountered isolated prefetching a mainframe
    HTML resource from the Google Search Result Page. Recorded for non-network
    error prefetches only. Redirects are not included here.
  </summary>
</histogram>

<histogram name="PrefetchProxy.Prefetch.Mainframe.RetryAfter" units="ms"
    expires_after="2024-04-25">
  <owner>curranmax@chromium.org</owner>
  <owner>ryansturm@chromium.org</owner>
  <owner>spelchat@chromium.org</owner>
  <summary>
    Records the duration of a Retry-After header on a 503 response to a
    mainframe prefetch request.
  </summary>
</histogram>

<histogram name="PrefetchProxy.Prefetch.Mainframe.TotalRedirects" units="count"
    expires_after="2023-06-25">
  <owner>curranmax@chromium.org</owner>
  <owner>ryansturm@chromium.org</owner>
  <owner>spelchat@chromium.org</owner>
  <summary>
    Records the total number of redirects encountered while doing all the
    prefetches on an eligible Google Search Result page. Only recorded when at
    least one prefetch was attempted.
  </summary>
</histogram>

<histogram name="PrefetchProxy.Prefetch.Mainframe.TotalTime" units="ms"
    expires_after="2023-08-27">
  <owner>curranmax@chromium.org</owner>
  <owner>ryansturm@chromium.org</owner>
  <owner>spelchat@chromium.org</owner>
  <summary>
    Records the total time taken when isolated prefetching a mainframe HTML
    resource from the Google Search Result Page. Recorded for successful
    non-network error prefetches only.
  </summary>
</histogram>

<histogram
    name="PrefetchProxy.Prefetch.NumExistingEligiblePrefetchWithMatchingURL"
    units="count" expires_after="2023-09-24">
  <owner>curranmax@chromium.org</owner>
  <owner>ryansturm@chromium.org</owner>
  <owner>spelchat@chromium.org</owner>
  <summary>
    Records the number of existing eligible prefetches with a matching URL from
    a different referring document when a new prefetch is requested. This is
    only recorded for prefetches where there is at least one existing prefetch
    with a matching URL.
  </summary>
</histogram>

<histogram name="PrefetchProxy.Prefetch.NumExistingPrefetchWithMatchingURL"
    units="count" expires_after="2023-08-27">
  <owner>curranmax@chromium.org</owner>
  <owner>ryansturm@chromium.org</owner>
  <owner>spelchat@chromium.org</owner>
  <summary>
    Records the number of existing prefetches with a matching URL from a
    different referring document when a new prefetch is requested. This is
    recorded everytime a prefetch is requested.
  </summary>
</histogram>

<histogram
    name="PrefetchProxy.Prefetch.NumExistingPrefetchWithMatchingURLAndReferrer"
    units="count" expires_after="2023-09-24">
  <owner>curranmax@chromium.org</owner>
  <owner>ryansturm@chromium.org</owner>
  <owner>spelchat@chromium.org</owner>
  <summary>
    Records the number of existing prefetches with a matching referring URL and
    matching prefetch URL from a different referring document when a new
    prefetch is requested. This is only recorded for prefetches where there is
    at least one existing prefetch with a matching URL.
  </summary>
</histogram>

<histogram
    name="PrefetchProxy.Prefetch.NumExistingPrefetchWithMatchingURLAndRenderFrameHost"
    units="count" expires_after="2023-09-24">
  <owner>curranmax@chromium.org</owner>
  <owner>ryansturm@chromium.org</owner>
  <owner>spelchat@chromium.org</owner>
  <summary>
    Records the number of existing prefetches with a matching referring render
    frame host and matching prefetch URL from a different referring document
    when a new prefetch is requested. This case can occur if and only if there
    was a same origin navigation that re-used the same render frame host and
    both pages requested to prefetch the same URL. This is only recorded for
    prefetches where there is at least one existing prefetch with a matching
    URL.
  </summary>
</histogram>

<histogram
    name="PrefetchProxy.Prefetch.NumExistingServablePrefetchWithMatchingURL"
    units="count" expires_after="2023-09-24">
  <owner>curranmax@chromium.org</owner>
  <owner>ryansturm@chromium.org</owner>
  <owner>spelchat@chromium.org</owner>
  <summary>
    Records the number of existing prefetches with a successfully completed
    prefetched responses and matching URL from a different referring document
    when a new prefetch is requested. This is only recorded for prefetches where
    there is at least one existing prefetch with a matching URL.
  </summary>
</histogram>

<histogram name="PrefetchProxy.Prefetch.RedirectChainSize" units="count"
    expires_after="2023-09-10">
  <owner>curranmax@chromium.org</owner>
  <owner>ryansturm@chromium.org</owner>
  <owner>spelchat@chromium.org</owner>
  <summary>
    The redirect chain size of a prefetch. This histogram is recorded once for
    each prefetch.
  </summary>
</histogram>

<histogram name="PrefetchProxy.Prefetch.StreamingURLLoaderFinalStatus"
    enum="PrefetchStreamingURLLoaderStatus" expires_after="2023-09-24">
  <owner>curranmax@chromium.org</owner>
  <owner>ryansturm@chromium.org</owner>
  <owner>spelchat@chromium.org</owner>
  <summary>
    Records the final status of the PrefetchStreamingURLLoader used to request
    the prefetch.

    This is recorded once for each prefetch that is requested using a streaming
    URL loader. It is recorded when the streaming URL loader is deleted which
    can be when: 1) the URL loader is canceled, 2) the URL loader completed
    serving the prefetch, or 3) the prefetch was deleted and not used.
  </summary>
</histogram>

<histogram name="PrefetchProxy.Proxy.Fallback.NetError" enum="NetErrorCodes"
    expires_after="2024-04-25">
  <owner>curranmax@chromium.org</owner>
  <owner>ryansturm@chromium.org</owner>
  <owner>spelchat@chromium.org</owner>
  <summary>
    Records the Net Error encountered when Chrome did a fallback from the
    prefetch proxy. Recorded only on fallbacks.
  </summary>
</histogram>

<histogram name="PrefetchProxy.Proxy.RespCode" enum="HttpResponseCode"
    expires_after="2023-08-27">
  <owner>curranmax@chromium.org</owner>
  <owner>ryansturm@chromium.org</owner>
  <owner>spelchat@chromium.org</owner>
  <summary>
    Records the HTTP response code encountered when connecting to the prefetch
    proxy CONNECT tunnel. Recorded every time Chrome gets CONNECT tunnel
    response headers.
  </summary>
</histogram>

<histogram name="PrefetchProxy.Redirect.NetworkContextStateTransition"
    enum="PrefetchRedirectNetworkContextTransition" expires_after="2023-09-10">
  <owner>curranmax@chromium.org</owner>
  <owner>ryansturm@chromium.org</owner>
  <owner>spelchat@chromium.org</owner>
  <summary>
    The network context transition required to handle a redirect while
    prefetching. Prefetches require an isolated network context if user data
    cannot be included in the prefetch. Otherwise the prefetch is made in the
    default network context. This histogram is recorded for every redirect.
  </summary>
</histogram>

<histogram name="PrefetchProxy.Redirect.Result" enum="PrefetchRedirectResult"
    expires_after="2023-09-10">
  <owner>curranmax@chromium.org</owner>
  <owner>ryansturm@chromium.org</owner>
  <owner>spelchat@chromium.org</owner>
  <summary>
    The result of receiving a redirect while prefetching. This histogram is
    recorded for every redirect.
  </summary>
</histogram>

<histogram name="PrefetchProxy.SpareRenderer.CountStartedOnSRP" units="count"
    expires_after="2024-04-25">
  <owner>curranmax@chromium.org</owner>
  <owner>ryansturm@chromium.org</owner>
  <owner>spelchat@chromium.org</owner>
  <summary>
    Records the number of spare renderers that were attempted to be started on
    the SRP, when the feature param is enabled.
  </summary>
</histogram>

<histogram name="PrefetchProxy.WasPrefetchTypeStateChangeValid"
    enum="BooleanSupported" expires_after="2023-04-25">
  <owner>curranmax@chromium.org</owner>
  <owner>chrome-brapp-loading@chromium.org</owner>
  <summary>
    Records whether a pretch type change was or was not supported by the
    PrefetchProxy code. A page can change the speculation rule for a given
    prefetch, but not all possible changes are currently supported. If the type
    change is not supported then the prefetch retains its initial type.

    This histogram is recorded each time the type of a prefetch is attempted to
    be changed.
  </summary>
</histogram>

</histograms>

</histogram-configuration>