tools/metrics/histograms/metadata/fastpair/histograms.xml

<!--
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 FastPair 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="FastPair.CreateBond.Latency" units="ms"
    expires_after="2023-07-02">
  <owner>jackshira@google.com</owner>
  <owner>dclasson@google.com</owner>
  <owner>brandosocarras@google.com</owner>
  <owner>chromeos-cross-device-eng@google.com</owner>
  <summary>
    Records the total time it takes for Fast Pair to finish creating a bond with
    the peripheral. Emitted when bonding completes. No metric is emitted on
    failure.
  </summary>
</histogram>

<histogram name="FastPair.GattConnection" enum="FastPairGattConnectionSteps"
    expires_after="2023-09-03">
  <owner>jackshira@google.com</owner>
  <owner>dclasson@google.com</owner>
  <owner>brandosocarras@google.com</owner>
  <owner>chromeos-cross-device-eng@google.com</owner>
  <summary>
    Records each sucessful step in the GATT Connection flow. These steps are: on
    connection start, on connection ready, on key-based characteristic found, on
    notifications enabled for the key-based pairing characteristic, and on
    connection established.
  </summary>
</histogram>

<histogram name="FastPair.GattServiceDiscovery.Latency" units="ms"
    expires_after="2023-07-02">
  <owner>jackshira@google.com</owner>
  <owner>dclasson@google.com</owner>
  <owner>brandosocarras@google.com</owner>
  <owner>chromeos-cross-device-eng@google.com</owner>
  <summary>
    Records the total time it takes for GATT service discovery. Emitted when
    GATT discovery is completed for service. No metric is emitted on failure.
  </summary>
</histogram>

<histogram name="FastPair.Handshake.AttemptCount" units="count"
    expires_after="2023-06-01">
  <owner>jackshira@google.com</owner>
  <owner>dclasson@google.com</owner>
  <owner>brandosocarras@google.com</owner>
  <owner>chromeos-cross-device-eng@google.com</owner>
  <summary>
    Records the number of attempts needed to successfully create a handshake.
    Currently the highest allowed attempt number is 3. Emitted following a
    successful handshake. No metric is emitted on failure.
  </summary>
</histogram>

<histogram name="FastPair.Handshake.EffectiveSuccessRate" enum="BooleanSuccess"
    expires_after="2023-06-01">
  <owner>jackshira@google.com</owner>
  <owner>dclasson@google.com</owner>
  <owner>brandosocarras@google.com</owner>
  <owner>chromeos-cross-device-eng@google.com</owner>
  <summary>
    Records the effective success rate of creating a handshake during the Fast
    Pair pairing protocol. Emitted following the attempted creation of the
    handshake and all retries.
  </summary>
</histogram>

<histogram name="FastPair.InitialPairing"
    enum="FastPairInitialSuccessFunnelEvent" expires_after="2023-10-22">
  <owner>jackshira@google.com</owner>
  <owner>dclasson@google.com</owner>
  <owner>brandosocarras@google.com</owner>
  <owner>chromeos-cross-device-eng@google.com</owner>
  <summary>
    Records each successful step in the Initial Pairing flow. These steps are:
    on notification click, on initialization start, on pairing start, on pairing
    complete, V1 device detected, guest mode detected, device already associated
    with the user's account, preparing to write the account key, account key
    written successfully, and on completion of the entire pairing process.
  </summary>
</histogram>

<histogram name="FastPair.KeyBasedNotify.Latency" units="ms"
    expires_after="2023-07-02">
  <owner>jackshira@google.com</owner>
  <owner>dclasson@google.com</owner>
  <owner>brandosocarras@google.com</owner>
  <owner>chromeos-cross-device-eng@google.com</owner>
  <summary>
    Records the total time it takes for the Fast Pair key based pairing notify
    session to begin. Emitted when a key based notify session has been
    successfully started. No metric is emitted on failure.
  </summary>
</histogram>

<histogram name="FastPair.KeyBasedWriteRequest.Latency" units="ms"
    expires_after="2023-07-02">
  <owner>jackshira@google.com</owner>
  <owner>dclasson@google.com</owner>
  <owner>brandosocarras@google.com</owner>
  <owner>chromeos-cross-device-eng@google.com</owner>
  <summary>
    Records the total time it takes for the Fast Pair key based write request to
    complete. Emitted when a key based write request has completed successfully.
    No metric is emitted on failure.
  </summary>
</histogram>

<histogram name="FastPair.PasskeyNotify.Latency" units="ms"
    expires_after="2023-07-02">
  <owner>jackshira@google.com</owner>
  <owner>dclasson@google.com</owner>
  <owner>brandosocarras@google.com</owner>
  <owner>chromeos-cross-device-eng@google.com</owner>
  <summary>
    Records the total time it takes for the Fast Pair passkey notify session to
    begin. Emitted when a passkey notify session has been successfully started.
    No metric is emitted on failure.
  </summary>
</histogram>

<histogram name="FastPair.PasskeyWriteRequest.Latency" units="ms"
    expires_after="2023-07-02">
  <owner>jackshira@google.com</owner>
  <owner>dclasson@google.com</owner>
  <owner>brandosocarras@google.com</owner>
  <owner>chromeos-cross-device-eng@google.com</owner>
  <summary>
    Records the total time it takes for the Fast Pair passkey request to
    complete. Emitted when a passkey write request has completed successfully.
    No metric is emitted on failure.
  </summary>
</histogram>

<histogram name="FastPair.RetroactivePairing"
    enum="FastPairRetroactiveSuccessFunnelEvent" expires_after="2023-10-08">
  <owner>jackshira@google.com</owner>
  <owner>dclasson@google.com</owner>
  <owner>brandosocarras@google.com</owner>
  <owner>chromeos-cross-device-eng@google.com</owner>
  <summary>
    Records each successful step in the Retroactive Pairing flow. Emitted on:
    device detected, GATT initialization started, writing account key, timed out
    writing account key, account key successfully written to the device, BLE
    address rotated, notification displayed to user, save requested by user
    (notification clicked), and account key saved to Footprints.
  </summary>
</histogram>

<histogram name="FastPair.SubsequentPairing"
    enum="FastPairSubsequentSuccessFunnelEvent" expires_after="2023-09-10">
  <owner>jackshira@google.com</owner>
  <owner>dclasson@google.com</owner>
  <owner>brandosocarras@google.com</owner>
  <owner>chromeos-cross-device-eng@google.com</owner>
  <summary>
    Records each sucessful step in the Subsequent Pairing flow. These steps are:
    on notification click, on initialization start, on pairing start, and on
    completion of the entire pairing process.
  </summary>
</histogram>

<histogram name="FastPair.{FastPairPairingProtocol}.Pairing"
    enum="FastPairProtocolPairingSteps" expires_after="2023-07-02">
  <owner>jackshira@google.com</owner>
  <owner>dclasson@google.com</owner>
  <owner>brandosocarras@google.com</owner>
  <owner>chromeos-cross-device-eng@google.com</owner>
  <summary>
    Records each sucessful step in the Protocol-based Pairing flow. These steps
    are: on pairing start, when retries have been exhausted, when device is
    already paired, on successful bond, on passkey negotiated, on passkey
    characteristic found, on notifications enabled for passkey characteristic,
    on passkey response, on passkey validation, on passkey confirmation, and on
    pairing complete.
  </summary>
  <token key="FastPairPairingProtocol">
    <variant name="InitialPairing" summary="Initial pairing protocol"/>
    <variant name="SubsequentPairing" summary="Subsequent pairing protocol"/>
  </token>
</histogram>

<histogram name="FastPair.{PairingScenario}.Initialization"
    enum="FastPairInitializePairingProcessEvent" expires_after="2023-06-01">
  <owner>jackshira@google.com</owner>
  <owner>dclasson@google.com</owner>
  <owner>brandosocarras@google.com</owner>
  <owner>chromeos-cross-device-eng@google.com</owner>
  <summary>
    Records the flow for the initialization of the GATT connection and the
    process for grabbing the classic address for the Bluetooth device and
    validating encryption keys. This flow is common across all three Fast Pair
    pairing scenarios. Emitted on the following steps: initialization started
    (when the process is kicked off), already pairing failure (when the device
    is already pairing when the notification is clicked), passed to pairing
    dialog (when a V1 device is detected, indicated that the device will not be
    logging the subsequent metrics in the flow), exhausted retries failure (on
    failure after three retry attempts), handshake reused (when a GATT handshake
    already exists, bypassing the GATT handshake flow for this attempt), and
    initialization complete (after the GATT handshake has completed, and the
    classic address for the device is known).
  </summary>
  <token key="PairingScenario">
    <variant name="InitialPairing"
        summary="the first time a user pairs a device via Fast Pair, device
                 needs to be in pairing mode, account key written to the
                 device to save it to their account, discovered via BLE
                 scanning"/>
    <variant name="RetroactivePairing"
        summary="user elects to save a device paired via classic Bluetooth
                 settings to their Google account, account key written to
                 device"/>
    <variant name="SubsequentPairing"
        summary="device is already saved to the user's account and is
                 discovered via not-discoverable advertisement, which means
                 the device does not have to be in pairing mode, no account
                 key saved to device, discovered via BLE scanning"/>
  </token>
</histogram>

<histogram name="FastPair.{PairingScenario}.Initialization.FailureReason"
    enum="FastPairPairFailure" expires_after="2023-06-01">
  <owner>jackshira@google.com</owner>
  <owner>dclasson@google.com</owner>
  <owner>brandosocarras@google.com</owner>
  <owner>chromeos-cross-device-eng@google.com</owner>
  <summary>
    Records the failure reason for initialization of the GATT connection and
    handshake (process for grabbing the classic address for the Bluetooth device
    and validating encryption keys). Emitted on every failure attempt. The
    initialization can succeed overall on a third retry, and still emit to this
    bucket on previous failed attempts. No metric is emitted on success. The
    only `FastPairPairFailure`s that will be related to this flow are: Pairing
    Device Lost, Data Encryptor Retrieval, Key-based Pairing Response Decrypt,
    Incorrect Key-based Pairing Response Type, Create GATT Connection, Pairing
    Device Lost Between GATT Connection Attempts, GATT Service Discovery
    Timeout, Key-based Pairing Characteristic Discovery, Key-based Pairing
    Characteristic Notify Session, Key-based Pairing Response Timeout, and
    Key-based Pairing Characteristic Write.
  </summary>
  <token key="PairingScenario">
    <variant name="InitialPairing"
        summary="the first time a user pairs a device via Fast Pair, device
                 needs to be in pairing mode, discovered via BLE scanning,
                 account key written to the device and saved to their account"/>
    <variant name="RetroactivePairing"
        summary="user elects to save a device paired via classic Bluetooth
                 settings to their Google account, account key written to
                 device"/>
    <variant name="SubsequentPairing"
        summary="device is already saved to the user's account and is
                 discovered via not-discoverable advertisement over BLE
                 scanning, the device does not have to be in pairing mode, no
                 account key saved to device"/>
  </token>
</histogram>

<histogram
    name="FastPair.{PairingScenario}.Initialization.RetriesBeforeSuccess"
    units="count" expires_after="2023-06-01">
  <owner>jackshira@google.com</owner>
  <owner>dclasson@google.com</owner>
  <owner>brandosocarras@google.com</owner>
  <owner>chromeos-cross-device-eng@google.com</owner>
  <summary>
    Records the number of retries that occurred before the successful completion
    of the initialization flow for the GATT connection and handshake. Emitted
    only on success of the initialization flow. No metric is emitted on failure.
  </summary>
  <token key="PairingScenario">
    <variant name="InitialPairing"
        summary="the first time a user pairs a device via Fast Pair, device
                 needs to be in pairing mode, discovered via BLE scanning,
                 account key written to the device and saved to their account"/>
    <variant name="RetroactivePairing"
        summary="user elects to save a device paired via classic Bluetooth
                 settings to their Google account, account key written to
                 device"/>
    <variant name="SubsequentPairing"
        summary="device is already saved to the user's account and is
                 discovered via not-discoverable advertisement over BLE
                 scanning, the device does not have to be in pairing mode, no
                 account key saved to device"/>
  </token>
</histogram>

</histograms>

</histogram-configuration>