tools/metrics/histograms/histograms.xml

Index: tools/metrics/histograms/histograms.xml
diff --git a/tools/metrics/histograms/histograms.xml b/tools/metrics/histograms/histograms.xml
index 90be084e2d504169d1c419182b208044378d373e..6a55d6f8d9cb0007d75380b2892389beda676bd6 100644
--- a/tools/metrics/histograms/histograms.xml
+++ b/tools/metrics/histograms/histograms.xml
@@ -75057,6 +75057,16 @@ http://cs/file:chrome/histograms.xml - but prefer this file for new entries.
   <summary>The outcome of Entry::ReadData in the simple cache.</summary>
 </histogram>
 
+<histogram base="true" name="SimpleCache.ReadStream1FromPrefetched"
+    enum="Boolean">
+  <owner>morlovich@chromium.org</owner>
+  <summary>
+    Whether a read from stream 1 was satisfied from prefetch data. Reported only

[Mark P, 2017/08/29 04:52:30]

nit: prefetch -> prefetched

[Maks Orlovich, 2017/08/29 13:24:13]

Done.

+    on first read op of entry (including if there are multiple readers, or even

[Mark P, 2017/08/29 04:52:30]

nit:
on first read op of entry
->
on the first read of the stream
(right?)

(for clarity)

[Maks Orlovich, 2017/08/29 13:24:12]

Indeed. Reads from other streams wouldn't affect this.

+    some writers).

[Mark P, 2017/08/29 04:52:30]

nit: Please define / explain "stream 1".  (Maybe as a sentence between those two
existing sentence.)

[Maks Orlovich, 2017/08/29 13:24:13]

(see below)

+  </summary>
+</histogram>
+
 <histogram base="true" name="SimpleCache.StaleIndexExtraEntryCount"
     units="entries">
   <owner>gavinp@chromium.org</owner>
@@ -75139,6 +75149,14 @@ http://cs/file:chrome/histograms.xml - but prefer this file for new entries.
   </summary>
 </histogram>
 
+<histogram base="true" name="SimpleCache.SyncOpenDidPrefetch" enum="Boolean">
+  <owner>morlovich@chromium.org</owner>
+  <summary>
+    Whether an attempt was made to prefetch the entire file when opening the
+    entry.

[Mark P, 2017/08/29 04:52:29]

nit: "entry" is vague.  Please be clearer.  URL?
Also, please state what causes this to be emitted, i.e., what causes an entry to
be "opened"?  Is this always user-initiated?

[Maks Orlovich, 2017/08/29 13:24:12]

So this is obvious when one knows the disk_cache API: there is a
disk_cache::Entry class, and one gets one via an OpenEntry method (or a
CreateEntry, but that one makes an empty one, so there is nothing to read). How
much context familiarity is expected of documentation strings here?

The "stream" thing is slightly different, in that the API docs only use it in a
couple spots, and generally use a vaguer "with the given index", which I am not
entirely fond off as its less specific; it might make sense to just say |index|
== 1 in the above descriptions, though, to match the header signature?

[Mark P, 2017/08/29 18:34:58]

Enough so that people who don't understand the feature can roughly understand
what's going on.
https://chromium.googlesource.com/chromium/src.git/+/HEAD/tools/metrics/histo...

For example, rather than saying "when opening the entry", say "when the
disk_cache API OpenEntry function is called."
This makes it clean enough so someone can have some idea where to look for
further documentation.
Perhaps even mention whether this API is called only by web developers or
whether it is called internally by Chrome too, as that can make a difference in
how to interpret changes in its value.
That doesn't sound any better to me: it's more technical yet no more
enlightening.
Conceptually what does "stream 1" or "stream at a given index (with index == 1)"
represent?  It must be something special, else you'd be logging all streams...
For example, is it simply the first stream that was written to?

[Maks Orlovich, 2017/08/29 19:04:10]

Done, using the full C++ name to make it clear it's not any sort of 
Web platform API, but rather an internal thing.
Gave some context. 

[Mark P, 2017/08/29 19:13:26]

Okay, this is good enough.  However, I should mention that we try to avoid
metrics and metrics descriptions that are logged deep inside function
calls.  This can be a problem when people refactor or add new code.
If the function then gets called in additional contexts, the meaning
of the histogram will change, though no one will likely end up realizing
and revising the description.  Or if people refactor the code, the
description no longer makes sense.

A good practice is to prefer histogram and user action descriptions
that are clearly tied to a user-initiated event, or something that happens
under particular conditions when dealing with a user event.

This is probably less of an issue because this function is only
called in one place at the moment and that isn't likely to change.
Nonetheless, I feel I should provide this advice.
That helps, thanks.

+  </summary>
+</histogram>
+
 <histogram base="true" name="SimpleCache.SyncOpenEntryAge" units="hours">
   <owner>gavinp@chromium.org</owner>
   <summary>
@@ -92363,6 +92381,7 @@ http://cs/file:chrome/histograms.xml - but prefer this file for new entries.
   <affected-histogram name="SimpleCache.QueueLatency.OpenEntry"/>
   <affected-histogram name="SimpleCache.ReadIsParallelizable"/>
   <affected-histogram name="SimpleCache.ReadResult"/>
+  <affected-histogram name="SimpleCache.ReadStream1FromPrefetched"/>
   <affected-histogram name="SimpleCache.StaleIndexExtraEntryCount"/>
   <affected-histogram name="SimpleCache.StaleIndexMissedEntryCount"/>
   <affected-histogram name="SimpleCache.StaleIndexQuality"/>
@@ -92377,6 +92396,7 @@ http://cs/file:chrome/histograms.xml - but prefer this file for new entries.
   <affected-histogram name="SimpleCache.SyncCreateResult_WithIndex"/>
   <affected-histogram name="SimpleCache.SyncCreateResult_WithoutIndex"/>
   <affected-histogram name="SimpleCache.SyncKeySHA256Result"/>
+  <affected-histogram name="SimpleCache.SyncOpenDidPrefetch"/>
   <affected-histogram name="SimpleCache.SyncOpenEntryAge"/>
   <affected-histogram name="SimpleCache.SyncOpenPlatformFileError"/>
   <affected-histogram name="SimpleCache.SyncOpenPlatformFileError_WithIndex"/>