<!--
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 Regional Capabilities
 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="RegionalCapabilities.ActiveRegionalProgram2"
    enum="ActiveRegionalProgram" expires_after="2027-02-14">
  <owner>ljjlee@google.com</owner>
  <owner>chrome-regionalcapabilities@google.com</owner>
  <summary>
    Records an overall active regional program for the profiles loaded in the
    current session, at the time the session is finalized. This histogram will
    be used by the UMA pipeline to tag all metrics in the session log, enabling
    per-program filtering and analysis.

    Emitted through ProvideCurrentSessionData, when a UMA session record is
    getting finalized. Is output only based on the currently-loaded profiles,
    and it is not output if there are zero currently-loaded profiles (context:
    https://crrev.com/c/7168123).
  </summary>
</histogram>

<histogram name="RegionalCapabilities.ActiveRegionalProgram3{Profile}"
    enum="ActiveRegionalProgram" expires_after="2027-01-03">
  <owner>ljjlee@google.com</owner>
  <owner>chrome-regionalcapabilities@google.com</owner>
  <summary>
    Records the regional program for the loaded profile when its session is
    finalized. This histogram will be used by the UMA pipeline to tag all
    metrics in the session log, enabling per-program filtering and analysis.

    Emitted through ProvideCurrentSessionData, when a UMA session record is
    getting finalized.

    {Profile}
  </summary>
  <token key="Profile" variants="ProfileIndex"/>
</histogram>

<histogram name="RegionalCapabilities.Debug.AndroidProgramResolution"
    enum="AndroidProgramResolution" expires_after="2027-01-03">
  <owner>dgn@chromium.org</owner>
  <owner>chrome-regionalcapabilities@google.com</owner>
  <summary>
    Reports the outcomes of the resolution between the Android-determined
    program and the Chrome active country, to track how often inconsistencies
    might be resolved by reverting the program to Default.
  </summary>
</histogram>

<histogram name="RegionalCapabilities.Debug.DefaultHighlightingResult"
    enum="BooleanSuccess" expires_after="2027-01-17">
  <owner>dgn@chromium.org</owner>
  <owner>chrome-regionalcapabilities@google.com</owner>
  <summary>
    Records whether the current default search engine was successfully found in
    the list of engines to be offered on the choice screen when highlighting is
    requested.

    Recorded when the profile is eligible to see a choice screen, and is putting
    together the data (list of engines, and if possible, which to highlight) to
    display on that choice screen. Should be emitted once per profile that show
    the choice screen, even if multiple windows (on desktop) are each showing a
    dialog.

    Warning: this histogram was expired from 2026-03-01 to 2026-05-04; data may
    be missing.
  </summary>
</histogram>

<histogram name="RegionalCapabilities.Debug.HasActiveRegionalProgram"
    enum="Boolean" expires_after="2027-01-03">
  <owner>dgn@chromium.org</owner>
  <owner>chrome-regionalcapabilities@google.com</owner>
  <summary>
    Records whether there is any active regional program for any of the loaded
    profiles. Recorded when a UMA session record is getting finalized. `false`
    if there are no loaded profiles, `true` otherwise.
  </summary>
</histogram>

<histogram name="RegionalCapabilities.Debug.ProgramSpecificExclusion"
    enum="RegionalProgramSpecificExclusion" expires_after="2027-01-03">
  <owner>dgn@chromium.org</owner>
  <owner>chrome-regionalcapabilities@google.com</owner>
  <summary>
    Reports occurrences of some of program specific conditions for which we
    don't have some dedicated histogram, but want to monitor for debugging
    purposes. See the individual events for record timing.
  </summary>
</histogram>

<histogram
    name="RegionalCapabilities.Debug.TriggeringEligibility.{SessionType}"
    enum="SearchEngineChoiceScreenConditions" expires_after="2027-01-03">
  <owner>dgn@chromium.org</owner>
  <owner>chrome-regionalcapabilities@google.com</owner>
  <summary>
    Records the eligibility when attempting to trigger the choice screen
    relative to whether this was during the Chrome first run or not.

    Aggregating both flows ends up being equivalent to looking at
    &quot;RegionalCapabilities.FunnelStage.Triggering&quot;.
  </summary>
  <token key="SessionType">
    <variant name="FirstRun"
        summary="Variant of the histogram associated with the Chrome first
                 run"/>
    <variant name="NotFirstRun"
        summary="Variant of the histogram associated with Chrome follow-up
                 runs"/>
  </token>
</histogram>

<histogram name="RegionalCapabilities.FallbackCountryMatching"
    enum="CountryMatchingStatus" expires_after="2026-11-15">
  <owner>dgn@chromium.org</owner>
  <owner>chrome-regionalcapabilities@google.com</owner>
  <summary>
    Reports on the relative status of the fallback profile country and the Finch
    latest country.

    Recorded when the profile is loaded, when we failed fetching the country
    from the primary source (e.g. Finch or Play). This can commonly happen
    during the FRE for some platforms. Otherwise,
    RegionalCapabilities.FetchedCountryMatching is recorded.
  </summary>
</histogram>

<histogram name="RegionalCapabilities.FetchedCountryMatching"
    enum="CountryMatchingStatus" expires_after="2027-01-17">
  <owner>dgn@chromium.org</owner>
  <owner>chrome-regionalcapabilities@google.com</owner>
  <summary>
    Reports on the relative status of the fetched profile country and the Finch
    latest country.

    Recorded when the profile is loaded, when we succeeded fetching the country
    from the primary source (e.g. Finch or Play). Otherwise,
    RegionalCapabilities.FallbackCountryMatching is recorded.
  </summary>
</histogram>

<!-- LINT.IfChange(RegionalCapabilities.FunnelStage.Eligibility) -->

<histogram name="RegionalCapabilities.FunnelStage.Eligibility{Profile}"
    enum="SearchEngineChoiceScreenConditions" expires_after="2027-01-03">
  <owner>dgn@chromium.org</owner>
  <owner>ljjlee@chromium.org</owner>
  <owner>chrome-regionalcapabilities@google.com</owner>
  <summary>
    Records the condition state on profile load for whether the profile is
    possibly eligible for a search engine choice screen.

    {Profile}
  </summary>
  <token key="Profile" variants="ProfileIndex"/>
</histogram>

<!-- LINT.ThenChange(tools/metrics/histograms/metadata/puma/histograms.xml:PUMA.RegionalCapabilities.FunnelStage.Eligibility) -->

<histogram name="RegionalCapabilities.FunnelStage.RegionalPresence"
    enum="RegionalProgramAndLocationMatch" expires_after="2027-02-07">
  <owner>dgn@chromium.org</owner>
  <owner>chrome-regionalcapabilities@google.com</owner>
  <summary>
    Reports on the relative status of the profile country and the Finch latest
    country, in the context of the selected regional program.

    Recorded when the profile is loaded, for profiles that have been determined
    to be in-scope for a non-default program. Only one bucket is logged for a
    profile, the most specific one. This means that &quot;region matches&quot;
    is not logged when &quot;country matches&quot; is logged.
  </summary>
</histogram>

<!-- LINT.IfChange(RegionalCapabilities.FunnelStage.Reported) -->

<histogram name="RegionalCapabilities.FunnelStage.Reported{Profile}"
    enum="RegionalCapabilitiesFunnelStage" expires_after="2027-01-31">
  <owner>dgn@chromium.org</owner>
  <owner>chrome-regionalcapabilities@google.com</owner>
  <summary>
    Reports on which stage of the regional capabilities funnel a given profile
    is in. (Internal-only: see go/chrome-taiyaki-metrics-dd for more info)

    Can be recorded by profiles on some key events like profile load or attempt
    to trigger a choice screen.

    {Profile}
  </summary>
  <token key="Profile" variants="ProfileIndex"/>
</histogram>

<!-- LINT.ThenChange(tools/metrics/histograms/metadata/puma/histograms.xml:PUMA.RegionalCapabilities.FunnelStage.Reported) -->

<!-- LINT.IfChange(RegionalCapabilities.FunnelStage.Triggering) -->

<histogram name="RegionalCapabilities.FunnelStage.Triggering{Profile}"
    enum="SearchEngineChoiceScreenConditions" expires_after="2027-01-03">
  <owner>dgn@chromium.org</owner>
  <owner>ljjlee@chromium.org</owner>
  <owner>chrome-regionalcapabilities@google.com</owner>
  <summary>
    Records the condition state at choice screen triggering attempt, for whether
    we are determining the profile to be eligible for a search engine choice
    screen. This is recorded every time the dynamic eligibility state is being
    checked, which might be as often as every page navigation on desktop, or app
    warm open on iOS. If a profile was deemed ineligible at profile load time
    (as recorded by the RegionalCapabilities.FunnelStage.Eligibility histogram),
    this histogram will not be recorded.

    {Profile}
  </summary>
  <token key="Profile" variants="ProfileIndex"/>
</histogram>

<!-- LINT.ThenChange(tools/metrics/histograms/metadata/puma/histograms.xml:PUMA.RegionalCapabilities.FunnelStage.Triggering) -->

<histogram name="RegionalCapabilities.LoadedCountrySource"
    enum="LoadedCapabilitiesCountrySource" expires_after="2027-01-10">
  <owner>dgn@chromium.org</owner>
  <owner>chrome-regionalcapabilities@google.com</owner>
  <summary>
    Reports which source of information is used by a given profile to determine
    the regional capabilities country.

    Recorded on each profile load.
  </summary>
</histogram>

<histogram name="RegionalCapabilities.PersistedCountryMatching"
    enum="CountryMatchingStatus" expires_after="2027-01-10">
  <owner>dgn@chromium.org</owner>
  <owner>chrome-regionalcapabilities@google.com</owner>
  <summary>
    Reports on the relative status of the persisted profile country and the
    Finch latest country.

    Recorded on each profile load.
  </summary>
</histogram>

</histograms>

</histogram-configuration>
