<!--
Copyright 2024 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 histograms related to
the visited url ranking component 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="GroupCreationSource">
  <variant name="CPA"
      summary="Tab groups created from contextual page action suggestions."/>
  <variant name="GTS"
      summary="Tab groups created from Grid Tab Switcher suggestions."/>
  <variant name="Unknown" summary="Tab groups created from an unknown source."/>
</variants>

<histogram name="GroupSuggestionsService.OpenedTabCount.Last10Mins"
    units="counts" expires_after="2026-03-15">
  <owner>ssid@chromium.org</owner>
  <owner>chrome-tab-group-eng@google.com</owner>
  <summary>
    Records the number of opened tabs in last 10 minutes, that are being
    considered as part of the group suggestion. Logged every time the group
    suggestion computation is run.
  </summary>
</histogram>

<histogram name="GroupSuggestionsService.SuggestionsCount" units="counts"
    expires_after="2027-01-24">
  <owner>ssid@chromium.org</owner>
  <owner>chrome-tab-group-eng@google.com</owner>
  <summary>
    Records the number of group suggestions that are available to show. Logged
    every time the group suggestion computation is run.
  </summary>
</histogram>

<histogram name="GroupSuggestionsService.SuggestionsCountAfterThrottling"
    units="counts" expires_after="2026-11-22">
  <owner>ssid@chromium.org</owner>
  <owner>chrome-tab-group-eng@google.com</owner>
  <summary>
    Records the number of group suggestions that are available to show after
    throttling. Logged every time the group suggestion is available to show.
  </summary>
</histogram>

<histogram name="GroupSuggestionsService.SuggestionThrottledReason"
    enum="TabGroupSuggestionThrottleReason" expires_after="2026-03-15">
  <owner>ckitagawa@chromium.org</owner>
  <owner>ssid@chromium.org</owner>
  <owner>chrome-tab-group-eng@google.com</owner>
  <summary>
    Records the reason why the group suggestion is throttled. Logged every time
    the group suggestion was computed and then throttled.
  </summary>
</histogram>

<histogram name="GroupSuggestionsService.SuggestionUiEvent"
    enum="SuggestionUiEvent" expires_after="2027-01-24">
  <owner>mfiaz@google.com</owner>
  <owner>ssid@chromium.org</owner>
  <owner>salg@google.com</owner>
  <summary>
    Records events related to the group suggestion service UI. Logged each time
    the respective event occurs.
  </summary>
</histogram>

<histogram
    name="GroupSuggestionsService.TabSwitches.PerGroup.{GroupCreationSource}"
    units="count" expires_after="2027-02-07">
  <owner>mfiaz@google.com</owner>
  <owner>ssid@chromium.org</owner>
  <owner>salg@google.com</owner>
  <summary>
    Records the average number of times per group a tab from a tab group was
    switched to the foreground. This is recorded when the application is
    stopped. The count is reset when the application is stopped. The source of
    the suggestion is {GroupCreationSource}.
  </summary>
  <token key="GroupCreationSource" variants="GroupCreationSource"/>
</histogram>

<histogram
    name="GroupSuggestionsService.TabSwitches.Total.{GroupCreationSource}"
    units="count" expires_after="2027-02-07">
  <owner>mfiaz@google.com</owner>
  <owner>ssid@chromium.org</owner>
  <owner>salg@google.com</owner>
  <summary>
    Records the number of times a tab from a tab group was switched to the
    foreground. This is recorded when the application is stopped. The count is
    reset when the application is stopped. The source of the suggestion is
    {GroupCreationSource}.
  </summary>
  <token key="GroupCreationSource" variants="GroupCreationSource"/>
</histogram>

<histogram
    name="GroupSuggestionsService.TimeSpent.PerGroup.{GroupCreationSource}"
    units="ms" expires_after="2026-11-29">
  <owner>mfiaz@google.com</owner>
  <owner>ssid@chromium.org</owner>
  <owner>salg@google.com</owner>
  <summary>
    Records the average time spent per group on a tab from a tab group per
    session. This is recorded when the application is stopped. The count is
    reset when the application is stopped. The source of the suggestion is
    {GroupCreationSource}.
  </summary>
  <token key="GroupCreationSource" variants="GroupCreationSource"/>
</histogram>

<histogram name="GroupSuggestionsService.TimeSpent.Total.{GroupCreationSource}"
    units="ms" expires_after="2027-02-07">
  <owner>mfiaz@google.com</owner>
  <owner>ssid@chromium.org</owner>
  <owner>salg@google.com</owner>
  <summary>
    Records the total time spent on a tab from a tab group per session. This is
    recorded when the application is stopped. The count is reset when the
    application is stopped. The source of the suggestion is
    {GroupCreationSource}.
  </summary>
  <token key="GroupCreationSource" variants="GroupCreationSource"/>
</histogram>

<histogram
    name="GroupSuggestionsService.TopSuggestionContainsLastTab.{ReasonVariant}"
    enum="Boolean" expires_after="2026-09-20">
  <owner>ckitagawa@chromium.org</owner>
  <owner>ssid@chromium.org</owner>
  <owner>chrome-tab-group-eng@google.com</owner>
  <summary>
    Records whether the top suggestion contains the tab that is in the last
    position in the tab model. Logged every time the group suggestion is
    available to show.
  </summary>
  <token key="ReasonVariant">
    <variant name="RecentlyOpened" summary="Recently opened"/>
    <variant name="SameOrigin" summary="Same origin"/>
    <variant name="SimilarSource" summary="Similar source"/>
    <variant name="SwitchedBetween" summary="Switched between"/>
  </token>
</histogram>

<histogram name="GroupSuggestionsService.TopSuggestionReason"
    enum="GroupSuggestionReason" expires_after="2026-11-22">
  <owner>ssid@chromium.org</owner>
  <owner>chrome-tab-group-eng@google.com</owner>
  <summary>
    Records the reason for the top group suggestion. Logged every time the group
    suggestion is available to show.
  </summary>
</histogram>

<histogram name="GroupSuggestionsService.TopSuggestionTabCount" units="counts"
    expires_after="2026-11-22">
  <owner>ssid@chromium.org</owner>
  <owner>chrome-tab-group-eng@google.com</owner>
  <summary>
    Records the number of tabs in the top group suggestion. Logged every time
    the group suggestion is available to show.
  </summary>
</histogram>

<histogram name="GroupSuggestionsService.TopSuggestionTabCount.{ReasonVariant}"
    units="counts" expires_after="2026-09-20">
  <owner>ssid@chromium.org</owner>
  <owner>chrome-tab-group-eng@google.com</owner>
  <summary>
    Records the number of tabs in the top group suggestion. Logged every time
    the group suggestion is available to show.
  </summary>
  <token key="ReasonVariant">
    <variant name="RecentlyOpened" summary="Recently opened"/>
    <variant name="SameOrigin" summary="Same origin"/>
    <variant name="SimilarSource" summary="Similar source"/>
    <variant name="SwitchedBetween" summary="Switched between"/>
  </token>
</histogram>

<histogram
    name="GroupSuggestionsService.TopSuggestionTabIndexAverageGap.{ReasonVariant}"
    units="counts" expires_after="2026-09-20">
  <owner>ckitagawa@chromium.org</owner>
  <owner>ssid@chromium.org</owner>
  <owner>chrome-tab-group-eng@google.com</owner>
  <summary>
    Records the average index difference between any tab with its adjacent tabs
    in the top suggestion. This is recorded once per top suggestion, and
    recorded every time when suggestion is available to show after throttling.
  </summary>
  <token key="ReasonVariant">
    <variant name="RecentlyOpened" summary="Recently opened"/>
    <variant name="SameOrigin" summary="Same origin"/>
    <variant name="SimilarSource" summary="Similar source"/>
    <variant name="SwitchedBetween" summary="Switched between"/>
  </token>
</histogram>

<histogram
    name="GroupSuggestionsService.TopSuggestionTabIndexMaxGap.{ReasonVariant}"
    units="counts" expires_after="2026-09-20">
  <owner>ckitagawa@chromium.org</owner>
  <owner>ssid@chromium.org</owner>
  <owner>chrome-tab-group-eng@google.com</owner>
  <summary>
    Records the max index difference between any tab with its adjacent tabs in
    the top suggestion. This is recorded once per top suggestion, and recorded
    every time when suggestion is available to show after throttling.
  </summary>
  <token key="ReasonVariant">
    <variant name="RecentlyOpened" summary="Recently opened"/>
    <variant name="SameOrigin" summary="Same origin"/>
    <variant name="SimilarSource" summary="Similar source"/>
    <variant name="SwitchedBetween" summary="Switched between"/>
  </token>
</histogram>

<histogram
    name="VisitedURLRanking.Fetch.History.Filter.ZeroDurationVisits.InOutPercentage"
    units="%" expires_after="2025-08-22">
  <owner>romanarora@chromium.org</owner>
  <owner>chrome-desktop-ntp@google.com</owner>
  <summary>
    Records the percentage of history annotated visits that have a visit
    duration greater than zero milliseconds and that will be leveratged to
    produce history aggregate data. Logged every time the History URL visit data
    fetcher executes and the associated features and params are enabled.
  </summary>
</histogram>

<histogram name="VisitedURLRanking.Fetch.{Fetcher}.Success"
    enum="BooleanSuccess" expires_after="2025-08-22">
  <owner>romanarora@chromium.org</owner>
  <owner>chrome-desktop-ntp@google.com</owner>
  <summary>
    Records the success or failure of a given data fetcher's execution. Logged
    every time the Visited URL Ranking Service's Fetch API is invoked and data
    fetchers executed.
  </summary>
  <token key="Fetcher">
    <variant name="History" summary="History"/>
    <variant name="Session" summary="Session"/>
    <variant name="TabModel" summary="Tab Model"/>
  </token>
</histogram>

<histogram name="VisitedURLRanking.Rank.NumVisits" units="counts"
    expires_after="2025-08-22">
  <owner>romanarora@chromium.org</owner>
  <owner>chrome-desktop-ntp@google.com</owner>
  <summary>
    Logs the number of URL visit aggregates that have been scored and will be
    returned to the caller. Logged as part of the Visited URL Ranking Service's
    Rank API call. Only logged when the visited url ranking service feature is
    enabled.
  </summary>
</histogram>

<histogram name="VisitedURLRanking.Request.Step.{Step}.Status"
    enum="VisitedURLRankingRequestStepStatus" expires_after="2025-08-22">
  <owner>romanarora@chromium.org</owner>
  <owner>chrome-desktop-ntp@google.com</owner>
  <summary>
    Records the status of a particular execution step of the Visited URL ranking
    service's APIs. Logged every time a client invokes one of the service's
    APIs. `Fetch` is recorded once per fetcher source participating in incoming
    Fetch API calls. `Rank` is recorded once per incoming Rank API call.
    `Transform` is recorded once per transformer participating in an incoming
    Fetch API call. Only logged when the visited url ranking service feature is
    enabled.
  </summary>
  <token key="Step">
    <variant name="Fetch" summary="Fetch"/>
    <variant name="Rank" summary="Rank"/>
    <variant name="Transform" summary="Transform"/>
  </token>
</histogram>

<histogram name="VisitedURLRanking.ScoredURLAction" enum="ScoredURLUserAction"
    expires_after="2025-05-25">
  <owner>romanarora@chromium.org</owner>
  <owner>chrome-desktop-ntp@google.com</owner>
  <summary>
    Records the most relevant action that took place for a scored URL visit
    resumption suggestion displayed on a UI, such as whether the user has seen,
    activated, or dismissed the suggestion. Logged by various Tab Resumption UI
    features when the user is presented with and/or interacts with a URL visit
    resumption suggestion. Only logged when the visited url ranking service
    feature is enabled.
  </summary>
</histogram>

<histogram
    name="VisitedURLRanking.TransformType.{URLVisitAggregatesTransformType}.InOutPercentage"
    units="%" expires_after="2025-08-10">
  <owner>romanarora@chromium.org</owner>
  <owner>chrome-desktop-ntp@google.com</owner>
  <summary>
    Records the percentage of outbound URL visit aggregates returned by a
    transform versus the inbound URL visit aggregates provided to the transform.
    Logged every time a URL visit aggregates transformer succeeded. Only logged
    if the visited url ranking service feature is enabled.
  </summary>
  <token key="URLVisitAggregatesTransformType">
    <variant name="BookmarkData" summary="Bookmark data"/>
    <variant name="DefaultAppUrlFilter" summary="Default app URL filter"/>
    <variant name="HistoryBrowserTypeFilter"
        summary="History browser type filter"/>
    <variant name="HistoryCategoriesFilter"
        summary="History caetgories filter"/>
    <variant name="HistoryVisibilityScoreFilter"
        summary="History visibility score filter"/>
    <variant name="None" summary="None"/>
    <variant name="RecencyFilter" summary="Recency filter"/>
    <variant name="SegmentationMetricsData"
        summary="Segmentation metrics data"/>
    <variant name="ShoppingData" summary="Shopping data"/>
    <variant name="TabEventsData" summary="Tab events data"/>
  </token>
</histogram>

<histogram
    name="VisitedURLRanking.TransformType.{URLVisitAggregatesTransformType}.Latency"
    units="ms" expires_after="2025-08-22">
  <owner>romanarora@chromium.org</owner>
  <owner>chrome-desktop-ntp@google.com</owner>
  <summary>
    Records the time elapsed in milliseconds (i.e. latency) when executing a
    given transformation. Logged every time a transformer succeeded and there
    were URL visit aggregates passed as input to the transform. Only logged if
    the visited url ranking service feature is enabled. Only logged when the
    tranform had data to process and when the transform was successful.
  </summary>
  <token key="URLVisitAggregatesTransformType">
    <variant name="BookmarkData" summary="Bookmark data"/>
    <variant name="DefaultAppUrlFilter" summary="Default app URL filter"/>
    <variant name="HistoryCategoriesFilter"
        summary="History caetgories filter"/>
    <variant name="HistoryVisibilityScoreFilter"
        summary="History visibility score filter"/>
    <variant name="None" summary="None"/>
    <variant name="RecencyFilter" summary="Recency filter"/>
    <variant name="SegmentationMetricsData"
        summary="Segmentation metrics data"/>
    <variant name="ShoppingData" summary="Shopping data"/>
  </token>
</histogram>

<histogram
    name="VisitedURLRanking.TransformType.{URLVisitAggregatesTransformType}.Success"
    enum="BooleanSuccess" expires_after="2025-08-10">
  <owner>romanarora@chromium.org</owner>
  <owner>chrome-desktop-ntp@google.com</owner>
  <summary>
    Records the success or failure of a transform type that was executed as part
    of the Visited URL Ranking Service's Fetch API call. Logged once for each
    transformer that excuted in the Fetch API call. Only logged if the visited
    url ranking service feature is enabled.
  </summary>
  <token key="URLVisitAggregatesTransformType">
    <variant name="BookmarkData" summary="Bookmark data"/>
    <variant name="DefaultAppUrlFilter" summary="Default app URL filter"/>
    <variant name="HistoryCategoriesFilter"
        summary="History caetgories filter"/>
    <variant name="HistoryVisibilityScoreFilter"
        summary="History visibility score filter"/>
    <variant name="None" summary="None"/>
    <variant name="RecencyFilter" summary="Recency filter"/>
    <variant name="SegmentationMetricsData"
        summary="Segmentation metrics data"/>
    <variant name="ShoppingData" summary="Shopping data"/>
  </token>
</histogram>

</histograms>

</histogram-configuration>
