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 ccb015218961048b5dfb1b1cfa73160813bd231d..54c1dc682726ca9879b889f0ae829730c5e79050 100644
--- a/tools/metrics/histograms/histograms.xml
+++ b/tools/metrics/histograms/histograms.xml
@@ -8723,6 +8723,15 @@ http://cs/file:chrome/histograms.xml - but prefer this file for new entries.
   </summary>
 </histogram>
 
+<histogram name="DeferredDocumentLoading.StatesV1"

[Ilya Sherman, 2016/09/06 21:29:17]

It looks like you're adding a new top-level category, "DeferredDocumentLoading".
 We generally discourage now top-level categories, because there's only one
global namespace, and most of the key ideas are already covered in it.  Hence,
I'd encourage you to explore to see whether there might already exist a
top-level category appropriate for this histogram.

If there isn't, then I'd encourage you to explore possible generalizations of
this name, e.g. to capture user agent interventions / mitigations more broadly. 
I have definitely seen other histograms landed for this effort, though I can't
at the moment recall which ones they were...

[dgrogan, 2016/09/07 17:54:50]

Sounds good, I put it under Navigation. The other candidate was PageLoad but
that seems to be pretty self-contained and I don't want to intrude.
Perhaps you were thinking of WebFont.InterventionResult* ?

[Ilya Sherman, 2016/09/07 18:00:38]

Yes, probably =)

+    enum="DocumentStateForDeferredLoading">
+  <owner>dgrogan@chromium.org</owner>
+  <summary>
+    Why and if subframes would be loaded in a world where we defer loading until
+    they are visible or are important for cross-origin communication.
+  </summary>
+</histogram>
+
 <histogram name="DevTools.ActionTaken" enum="DevToolsAction">
   <owner>sergeyv@chromium.org</owner>
   <owner>vsevik@chromium.org</owner>
@@ -74633,6 +74642,11 @@ http://cs/file:chrome/histograms.xml - but prefer this file for new entries.
   <int value="3" label="Keyboard"/>
 </enum>
 
+<enum name="DocumentStateForDeferredLoading" type="int">
+  <int value="0" label="Created"/>
+  <int value="1" label="WouldLoadBecauseVisible"/>

[Ilya Sherman, 2016/09/06 21:29:17]

Should there also be an entry related to cross-origin communication, and
possibly others?

[dgrogan, 2016/09/07 17:54:50]

Depends on the accepted best practices, with which I am not familiar. I assumed
that I should only add entries here once the code actually logs them. Is that
wrong? Anything I add here would be merely speculative at this point...

[Ilya Sherman, 2016/09/07 18:00:38]

Indeed, the best practice is to only list values that match the implementation. 
It's just surprising that the histogram description lists more things than are
actually logged.

[dgrogan, 2016/09/07 18:09:38]

Ah, I wrote the description aspirationally but later cut the cross-origin
communication part. Description now fixed.

+</enum>
+
 <enum name="DocumentWriteGatedEvaluation" type="int">
   <int value="0" label="Script too long"/>
   <int value="1" label="No likely external script write"/>