<!--
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 HangWatcher 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
[email protected].
-->
<histogram-configuration>
<histograms>
<variants name="BrowserProcessAndThreadType">
<variant name="BrowserProcess.IOThread"
summary="the Browser process IO-Thread"/>
<variant name="BrowserProcess.ThreadPool"
summary="a WorkerPool Thread the Browser process"/>
<variant name="BrowserProcess.UIThread"
summary="the Browser process UI-Thread"/>
</variants>
<variants name="LifetimePhase">
<variant name="Normal" summary="normal browser runtime"/>
<variant name="Shutdown" summary="shutdown"/>
</variants>
<variants name="MaybeBestEffort">
<variant name=""
summary="Sampled while running in a normal priority process for the
entire sample."/>
<variant name=".BestEffort"
summary="Sampled while running at Process::Priority::kBestEffort."/>
</variants>
<variants name="NonBrowserProcessAndThreadType">
<variant name="RendererProcess.IOThread"
summary="the IO-Thread of a Renderer process"/>
<variant name="RendererProcess.MainThread"
summary="the Main Thread of a Renderer process"/>
<variant name="UtilityProcess.IOThread"
summary="the IO-Thread of a Utility process"/>
<variant name="UtilityProcess.MainThread"
summary="the Main Thread of a Utility process"/>
</variants>
<variants name="ProcessType">
<variant name="BrowserProcess"/>
<variant name="RendererProcess"/>
<variant name="UtilityProcess"/>
</variants>
<histogram name="HangWatcher.IsThreadHung.{BrowserProcessAndThreadType}"
enum="BooleanHung" expires_after="2025-02-09">
<owner>[email protected]</owner>
<owner>[email protected]</owner>
<summary>
Every 10 seconds, a boolean is recorded to this histogram to indicate
whether {BrowserProcessAndThreadType} was hung. The thread is hung if the
current work unit started running more than 10 seconds ago and this was not
labeled as "working as intended" by InvalidateActiveExpectations()
(Prior to 2021-07-09 with IgnoreHangsInScope). Recording is skipped if the
hang watcher detects an irregular heartbeat (e.g. when the machine sleeps).
Warning: Starting with 104.0.5112.79 hang counts have gone way up on macOS
which is due to additional coverage added and not necessarily to
regressions. See: crrev.com/c/3035824
Deprecated. For Chrome M127 and higher, look at
HangWatcher.IsThreadHung.<process>.<phase> instead.
</summary>
<token key="BrowserProcessAndThreadType"
variants="BrowserProcessAndThreadType"/>
</histogram>
<histogram
name="HangWatcher.IsThreadHung.{BrowserProcessAndThreadType}.{LifetimePhase}"
enum="BooleanHung" expires_after="never">
<!-- expires-never: Staple top-level metric for chrome-catan@. -->
<owner>[email protected]</owner>
<owner>[email protected]</owner>
<summary>
Every 10 seconds, a boolean is recorded to this histogram to indicate
whether {BrowserProcessAndThreadType} was hung during {LifetimePhase}. The
thread is hung if the current work unit started running more than 10 seconds
ago and this was not labeled as "working as intended" by
InvalidateActiveExpectations(). Recording is skipped if the hang watcher
detects an irregular heartbeat (e.g. when the machine sleeps).
</summary>
<token key="BrowserProcessAndThreadType"
variants="BrowserProcessAndThreadType"/>
<token key="LifetimePhase" variants="LifetimePhase"/>
</histogram>
<histogram
name="HangWatcher.IsThreadHung.{NonBrowserProcessAndThreadType}{MaybeBestEffort}"
enum="BooleanHung" expires_after="never">
<!-- expires-never: Staple top-level metric for chrome-catan@. -->
<owner>[email protected]</owner>
<owner>[email protected]</owner>
<summary>
Every 10 seconds, a boolean is recorded to this histogram to indicate
whether {NonBrowserProcessAndThreadType} was hung. The thread is hung if the
current work unit started running more than 10 seconds ago and this was not
labeled as "working as intended" by InvalidateActiveExpectations()
(Prior to 2021-07-09 with IgnoreHangsInScope). Recording is skipped if the
hang watcher detects an irregular heartbeat (e.g. when the machine sleeps).
Warning: Starting with 104.0.5112.79 hang counts have gone way up on macOS
which is due to additional coverage added and not necessarily to
regressions. See: crrev.com/c/3035824
</summary>
<token key="NonBrowserProcessAndThreadType"
variants="NonBrowserProcessAndThreadType"/>
<token key="MaybeBestEffort" variants="MaybeBestEffort"/>
</histogram>
<histogram name="HangWatcher.SleepDrift.{ProcessType}" units="ms"
expires_after="2021-10-23">
<owner>[email protected]</owner>
<owner>[email protected]</owner>
<summary>
HangWatcher is a class that periodically checks on watched threads to see if
they are making progress or if they are hung. This metric is recorded when
the HangWatcher resumes from sleeping for its next watch time. The value is
the time difference between when the HangWatcher woke up and the planned
wake-up time. Not waking up in time is a bad state. It could be caused by an
overloaded machine or another problem like system sleep. Knowing whether the
HangWatcher wakes up in a timely manner in the average case can help analyse
trial results and is interesting to track over time. An increasing value for
this histogram could hint at a larger problem and would prevent
missinterpreting a reduced inflow of hang reports as a improvement when it
is in fact caused by hindered capabilities.
</summary>
<token key="ProcessType" variants="ProcessType"/>
</histogram>
<histogram name="HangWatcher.{ProcessType}.UncoveredStartupTime" units="ms"
expires_after="2023-12-22">
<owner>[email protected]</owner>
<owner>[email protected]</owner>
<summary>
Because HangWatcher start is delayed until the sandbox is initialized on
Linux and ChromeOS, this measures the delta between the time HangWatcher
would have started in an unsandboxed process and the time the HangWatcher
actually started. The metric is emitted in the process type's main function
(e.g. RendererMain, UtilityMain) right after the sandbox is engaged and
right before HangWatcher is started.
This will be used to evaluate whether hangs are missed during startup
because of this delay.
</summary>
<token key="ProcessType" variants="ProcessType"/>
</histogram>
</histograms>
</histogram-configuration>
Codebase Browser
chromium