0

android: Update histograms.xml for cold start metrics

We are switching to v4 metrics for startup. Adjust the description of
the metric in histograms.xml to match the fact that it is the primary
one. Rewrite the descriptions of the previous versions to focus only on
the differences. This will allow readers to avoid doing the diff
themselves.

Bug: 384084655
Change-Id: Ief23b69bb15586737186a450c58bb0eceee2f2a8
Reviewed-on: https://chromium-review.googlesource.com/c/chromium/src/+/6197642
Reviewed-by: Sean Maher <spvw@chromium.org>
Commit-Queue: Egor Pasko <pasko@chromium.org>
Cr-Commit-Position: refs/heads/main@{#1414348}
This commit is contained in:
Egor Pasko
2025-01-31 12:43:43 -08:00
committed by Chromium LUCI CQ
parent 063512a061
commit 3519fdc637
2 changed files with 75 additions and 151 deletions
docs/speed/startup
tools/metrics/histograms/metadata/startup

@ -23,8 +23,8 @@ Activity is rendered. For the latter two, we care both about:
Here are some UMA metrics that measure start-up (UMA's UI has descriptions):
* `Startup.Android.Cold.TimeToFirstVisibleContent2`
* `Startup.Android.Cold.TimeToFirstNavigationCommit2.Tabbed`
* `Startup.Android.Cold.TimeToFirstVisibleContent4`
* `Startup.Android.Cold.TimeToFirstNavigationCommit3.Tabbed`
* `Browser.PaintPreview.TabbedPlayer.TimeToFirstBitmap`
* `Startup.Android.Cold.TimeToFirstContentfulPaint3.Tabbed`

@ -180,12 +180,23 @@ chromium-metrics-reviews@google.com.
The first difference is to record navigation commits happening before
post-native initialization. The second modifications is not to record
samples when FRE is shown.
This metric was replaced by the
Startup.Android.Cold.TimeToFirstNavigationCommit2.Tabbed. The differences
are:
- The new metric utilizes the ColdStartTracker to record 5x more valid
samples than the current one.
- The new metric adds back the .WebApk variant
</summary>
</histogram>
<histogram
name="Startup.Android.Cold.TimeToFirstNavigationCommit3.{ActivityType}"
units="ms" expires_after="2025-06-08">
units="ms" expires_after="never">
<!-- expires-never: used for a guiding metric: TimeToFirstVisibleContent4 -->
<owner>pasko@chromium.org</owner>
<owner>agrieve@chromium.org</owner>
<owner>nafisabedin@google.com</owner>
@ -211,18 +222,6 @@ chromium-metrics-reviews@google.com.
6. when the first navigation was preceded by showing a NTP (New Tab Page).
This metric aims to replace
Startup.Android.Cold.TimeToFirstNavigationCommit2.Tabbed due to a loss of
samples for the v2 metric as well as add a .WebApk variant similar to the v1
metric.
It utilizes ColdStartTracker and records 5x more samples than what the v2
metric currently records. The Experimental metric,
Startup.Android.Experimental.FirstNavigationCommit.Tabbed.ColdStartTracker
is currently being used to diagnose A/B problems running in the field so the
new metric will replace it and the v2 metric once it approximately reaches
the counts of the Experimental one on Chrome Stable.
NOTE: This metric is broken before October 2024 on Pixel 6+ on Android 14+
due to an issue with the recording of BrowserProcessCreationReason affecting
ColdStartTracker downstream.
@ -234,146 +233,50 @@ chromium-metrics-reviews@google.com.
</histogram>
<histogram name="Startup.Android.Cold.TimeToFirstVisibleContent" units="ms"
expires_after="never">
<!-- expires-never: guiding metric (internal: go/chrome-browser-guiding-metrics) -->
expires_after="2025-06-30">
<owner>yfriedman@chromium.org</owner>
<owner>pasko@chromium.org</owner>
<owner>fredmello@chromium.org</owner>
<owner>chrome-analysis-team@google.com</owner>
<summary>
The time from the first Chrome tabbed activity creation to the moment Chrome
first appears ready to the user.
This histogram (the v1) will soon stop being recorded. It was replaced by
the v2 (Startup.Android.Cold.TimeToFirstVisibleContent2), which was then
superceded by the v4 (Startup.Android.Cold.TimeToFirstVisibleContent4).
This metric captures when the omnibox is painted and either a navigation has
committed or a Paint Preview is shown. The intent is to reflect Clank's
perceived cold start performance regardless of different launch paths, while
controlling for the factors that we have the most direct influence over and
minimizing external factors. Note that network connectivity is mostly but
not entirely omitted as it does impact the initial response time for a site
which impacts the omnibox UX and loading metric.
Bug fixed by the v2:
This metric captures the value of the first emitted metric out of the
'Startup.Android.Cold.TimeToFirstNavigationCommit.Tabbed' and
'Browser.PaintPreview.TabbedPlayer.TimeToFirstBitmap' metrics and emits the
value.
This metric is only recorded once per application lifetime during cold
startup i.e. when Chrome's native library is not loaded at first activity
creation. Specifically, it is recorded for the first foreground committed
http(s) URL in the primary frame if that first navigation is not: an error,
same-document navigation, or fragment navigation.
This metric is expected be stable from milestone to milestone. Updating
Chrome or the Android system image on the device are expected to result in a
noticeable slowdown on the first cold startup after. The total counts
changes for this histogram are not of significant importance; however, a
non-trivial increase in total counts could signal more background kills, for
example.
This metric is not recorded:
- If another navigation occurs before the first navigation commit and the
Paint Preview show.
- If the navigation is pre-warmed, is a background navigation, or fails to
be committed (e.g. cancelled, network error, or error due to lack of
connectivity).
- If the activity was ever backgrounded between activity creation and this
metric reporting.
- If the app opens to the Chrome Start page.
- For WebApps, PWAs or WebApks.
- For NTP.
Bugs:
- This metric does not get recorded when the first navigation commit happens
before post-native initialization. This behaviour is not intentional, see
crbug.com/1273097. TimeToFirstVisibleContent2 addresses this issue and aims
to become the replacement.
This histogram is of special interest to the chrome-analysis-team@. Do not
change its semantics or retire it without talking to them first.
- The v2 metric does not get recorded when the first navigation commit
happens before post-native initialization. See crbug.com/1273097.
</summary>
</histogram>
<histogram name="Startup.Android.Cold.TimeToFirstVisibleContent2" units="ms"
expires_after="2025-06-30">
<owner>yfriedman@chromium.org</owner>
<owner>pasko@chromium.org</owner>
<owner>fredmello@chromium.org</owner>
<summary>
This histogram (the v2) will soon stop being recorded. It is superceded by
the v4: Startup.Android.Cold.TimeToFirstVisibleContent4. Compared to v2 the
new histogram fixes a few issues:
- v2 relies on Startup.Android.Cold.TimeToFirstNavigationCommit2.Tabbed as
its submetric, and v4 takes the updated
Startup.Android.Cold.TimeToFirstNavigationCommit3.Tabbed as the source
- v2 marks the startup as Cold if during creation of the first Activity the
native library was not loaded
</summary>
</histogram>
<histogram name="Startup.Android.Cold.TimeToFirstVisibleContent4" units="ms"
expires_after="never">
<!-- expires-never: guiding metric (internal: go/chrome-browser-guiding-metrics) -->
<owner>yfriedman@chromium.org</owner>
<owner>pasko@chromium.org</owner>
<owner>fredmello@chromium.org</owner>
<owner>chrome-analysis-team@google.com</owner>
<summary>
The time from the first Chrome tabbed activity creation to the moment Chrome
first appears ready to the user.
This metric captures when the omnibox is painted and either a navigation has
committed or a Paint Preview is shown. The intent is to reflect Clank's
perceived cold start performance regardless of different launch paths, while
controlling for the factors that we have the most direct influence over and
minimizing external factors. Note that network connectivity is mostly but
not entirely omitted as it does impact the initial response time for a site
which impacts the omnibox UX and loading metric.
This metric captures the value of the first emitted metric out of the
'Startup.Android.Cold.TimeToFirstNavigationCommit.Tabbed' and
'Browser.PaintPreview.TabbedPlayer.TimeToFirstBitmap' metrics and emits the
value.
This metric is only recorded once per application lifetime during cold
startup i.e. when Chrome's native library is not loaded at first activity
creation. Specifically, it is recorded for the first foreground committed
http(s) URL in the primary frame if that first navigation is not: an error,
same-document navigation, or fragment navigation.
This metric is expected be stable from milestone to milestone. Updating
Chrome or the Android system image on the device are expected to result in a
noticeable slowdown on the first cold startup after. The total counts
changes for this histogram are not of significant importance; however, a
non-trivial increase in total counts could signal more background kills, for
example.
This metric is not recorded:
- If another navigation occurs before the first navigation commit and the
Paint Preview show.
- If the navigation is pre-warmed, is a background navigation, or fails to
be committed (e.g. cancelled, network error, or error due to lack of
connectivity).
- If the activity was ever backgrounded between activity creation and this
metric reporting.
- If the app opens to the Chrome Start page.
- For WebApps, PWAs or WebApks.
- For NTP.
This metrics has the same semantics as
Startup.Android.Cold.TimeToFirstVisibleContent, except with the
crbug.com/1273097 fixed. In other words, this v2 metric also records a
sample when the first navigation commit happens before post-native
initialization.
This histogram is of special interest to the chrome-analysis-team@. Do not
change its semantics or retire it without talking to them first.
</summary>
</histogram>
<histogram name="Startup.Android.Cold.TimeToFirstVisibleContent4" units="ms"
expires_after="2025-07-27">
<owner>yfriedman@chromium.org</owner>
<owner>pasko@chromium.org</owner>
<owner>fredmello@chromium.org</owner>
<owner>nafisabedin@google.com</owner>
<owner>chrome-ds@google.com</owner>
<summary>
The time from the first Chrome tabbed activity creation to the moment Chrome
first appears ready to the user.
@ -391,20 +294,41 @@ chromium-metrics-reviews@google.com.
'Browser.PaintPreview.TabbedPlayer.TimeToFirstBitmap' metrics and emits the
value, skipping the record when both are missing.
The metric is meant to replace
Startup.Android.Cold.TimeToFirstVisibleContent2 as a guardrail metric and
therefore has the same semantics as the v2 version except with one of the
sub-metrics changed. For the v2 metric,
Startup.Android.Cold.TimeToFirstNavigationCommit2.Tabbed, was one of the
sub-metrics, however, moving the native library initialization to be earlier
resulted in a loss of samples. Therefore, the new sub-metric,
TimeToFirstNavigationCommit3.Tabbed, utilizes ColdStartTracker for its lower
maintenance risks, and preservation of the good properties from v2, all
while providing 5x more samples.
This metric is only recorded once per application lifetime, and only for the
cold starts. An important requirement for the startup to be Cold is that the
Tabbed Activity has to be the process creation Reason. See histogram
Startup.Android.BrowserProcessCreationReason and code in ColdStartTracker.
Determining the process creation reason is only reliable starting at Android
P.
The v4 metric comes with a fix to how BrowserProcessCreationReason is
recorded starting with Pixel 6+ on Android 14+ which resulted in incorrect
downstream behaviour with ColdStartTracker.
Specifically, it is recorded for the first foreground committed http(s) URL
in the primary frame if that first navigation is not: an error,
same-document navigation, or fragment navigation.
This metric is not recorded:
- If another navigation occurs before the first navigation commit and the
Paint Preview show.
- If the navigation is pre-warmed, is a background navigation, or fails to
be committed (e.g. cancelled, network error, or error due to lack of
connectivity).
- If the activity was ever backgrounded between activity creation and this
metric reporting.
- If the app opens to the Chrome Start page.
- For WebApps, PWAs or WebApks.
- For NTP.
This metric is expected be stable from milestone to milestone. Updating
Chrome or the Android system image on the device are expected to result in a
noticeable slowdown on the first cold startup after.
This histogram is of special interest to the chrome-ds@. Do not change its
semantics or retire it without talking to them first.
</summary>
</histogram>