Add first iteration of documentation for chrome://metrics-internals

Bug: 1363747
Change-Id: Ib574e9d103d8d9e13eeccb359d5b9ad62e51352c
Reviewed-on: https://chromium-review.googlesource.com/c/chromium/src/+/4108390
Reviewed-by: Robert Kaplow <rkaplow@chromium.org>
Commit-Queue: Luc Nguyen <lucnguyen@google.com>
Cr-Commit-Position: refs/heads/main@{#1084718}

components/metrics/debug/README.md

@@ -0,0 +1,47 @@
+# Metrics Internals Debug Page
+
+**chrome://metrics-internals** is a debug page that reports the state of various
+metrics systems.
+
+The page displays logs that have been collected by the UMA metrics service,
+which are eventually sent to Google servers. These logs can be exported, and
+their proto data can later be inspected using a Google-internal tool:
+[go/metrics-internals-inspector](http://go/metrics-internals-inspector).
+
+On debug builds, the page will show all logs collected since browser startup,
+including logs from previous sessions that were not sent yet. On release builds,
+the page will instead show logs collected since the page was opened. This
+difference is mostly due to memory concerns (on official releases, we don't want
+logs to be lingering in memory since they can be relatively large).
+
+> Tip: By using the `--export-uma-logs-to-file=FILE_PATH` command line flag, all
+logs collected throughout the Chrome session will be exported to the passed
+`FILE_PATH` on shutdown (the file is created if it does not already exist). For
+release builds, this flag also has the effect of showing all logs collected
+since browser startup on the page.
+
+> Note: The delay between logs being closed can be [long]. If you are just
+testing to see if a certain metric (e.g., histogram, user action, etc.) is being
+properly sent to Google servers and you want logs to be collected more often,
+you can use the `--metrics-upload-interval=N` command line flag, where `N` is in
+seconds and is at least `20`.
+
+[long]: https://source.chromium.org/chromium/chromium/src/+/main:components/metrics/net/cellular_logic_helper.cc;l=18,21;drc=8ba1bad80dc22235693a0dd41fe55c0fd2dbdabd
+
+Unlike other metrics debug pages ([chrome://user-actions], **chrome://ukm**, and
+[chrome://histograms]), this page focuses mainly on what has actually been sent
+to Google servers. For example, it is possible that a user action shown on
+[chrome://user-actions] is never actually sent (e.g., due to being [truncated]
+for bandwidth reasons). Similarly, a source shown on **chrome://ukm** might be
+[dropped] and hence never be sent. Or, a histogram shown on
+[chrome://histograms] would not have been collected under regular circumstances
+(e.g., subprocess histograms, which are normally only collected periodically,
+but are collected [immediately] when loading **chrome://histograms**). In other
+words, this page displays the actual logs that have been created and sent,
+without modifications.
+
+[chrome://user-actions]: https://chromium.googlesource.com/chromium/src/+/master/tools/metrics/actions/README.md#Testing
+[chrome://histograms]: https://chromium.googlesource.com/chromium/src/+/master/tools/metrics/histograms/README.md#Testing
+[truncated]: https://source.chromium.org/chromium/chromium/src/+/main:components/metrics/metrics_log.cc;l=552;drc=38321ee39cd73ac2d9d4400c56b90613dee5fe29
+[dropped]: https://source.chromium.org/chromium/chromium/src/+/main:components/ukm/ukm_recorder_impl.cc;l=362;drc=38321ee39cd73ac2d9d4400c56b90613dee5fe29
+[immediately]: https://source.chromium.org/chromium/chromium/src/+/main:content/browser/metrics/histograms_internals_ui.cc;l=100;drc=5e521f43547ebdce502a555c5edb3a18f0c87a8a

tools/metrics/actions/README.md

@@ -112,6 +112,9 @@ In addition to testing interactively, unit tests can check the number of times a
 user action was emitted. See [user_action_tester.h](https://cs.chromium.org/chromium/src/base/test/metrics/user_action_tester.h)
 for details.
 
+See also `chrome://metrics-internals` ([docs](https://chromium.googlesource.com/chromium/src/+/master/components/metrics/debug/README.md))
+for more thorough manual testing if needed.
+
 ## Interpreting the resulting data
 
 The top of [go/uma-guide](http://go/uma-guide) has good advice on how to go

tools/metrics/histograms/README.md

@@ -511,13 +511,17 @@ the values emitted to are correct. Finally, for count histograms, make sure
 that buckets capture enough precision for your needs over the range.
 
 Pro tip: You can filter the set of histograms shown on `chrome://histograms` by
-specifying a prefix. For example, `chrome://histograms/Extensions.Load` shows
-only histograms whose names match the pattern "Extensions.Load*".
+appending to the URL. For example, `chrome://histograms/UserActions` shows
+only histograms whose names contain "UserActions", such as
+"UMA.UserActionsCount".
 
 In addition to testing interactively, you can have unit tests examine the
 values emitted to histograms. See [histogram_tester.h](https://cs.chromium.org/chromium/src/base/test/metrics/histogram_tester.h)
 for details.
 
+See also `chrome://metrics-internals` ([docs](https://chromium.googlesource.com/chromium/src/+/master/components/metrics/debug/README.md))
+for more thorough manual testing if needed.
+
 ## Interpreting the Resulting Data
 
 The top of [go/uma-guide](http://go/uma-guide) has good advice on how to go