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 7897d0c7627e8c65badeeb72110398d585be5354..341a2e883eb6746495120c42037695cfd1e24d28 100644
--- a/tools/metrics/histograms/histograms.xml
+++ b/tools/metrics/histograms/histograms.xml
@@ -46700,6 +46700,247 @@ http://cs/file:chrome/histograms.xml - but prefer this file for new entries.
   </summary>
 </histogram>
 
+<histogram name="PageLoad.Clients.Ads.Google.AdFrameCount" units="AdFrames">

[Ilya Sherman, 2017/04/26 00:09:44]

nit: Units are allowed to have spaces in them.  Probably "Ad frames" is the most
appropriate spelling, since this will be displayed as either a table column
header or an axis label.

[jkarlin, 2017/04/26 16:34:54]

Done.

+  <owner>jkarlin@chromium.org</owner>
+  <summary>
+    The number of frames on the page identified as Google Ad Frames.
+
+    For pages with zero ad frames, the other PageLoad.Clients.Ads metrics are
+    not recorded.
+
+    An ad frame consists of the identified ad frame and all of its children
+    (which may also be ads, but are counted as part of the ancestor ad frame).

[Ilya Sherman, 2017/04/26 00:09:45]

This parenthetical statement is not entirely clear to me.  Are you saying that
if ad frames are nested in one another, only the topmost ad frame is counted for
this metric?

[jkarlin, 2017/04/26 16:34:55]

Fixed.

+  </summary>
+</histogram>
+
+<histogram name="PageLoad.Clients.Ads.Google.AdFrameCount.TopLevel"
+    units="Frames">
+  <owner>jkarlin@chromium.org</owner>
+  <summary>
+    The number of top-level frames on the page identified as Google Ad Frames.

[Ilya Sherman, 2017/04/26 00:09:44]

What is a top-level frame?  I would have expected it to be the main document,
but I guess you might mean frames that are children of the main document?  Might
be worth clarifying, if this is not a standard terminology that I just happen to
be unfamiliar with.

[jkarlin, 2017/04/26 16:34:54]

Clarified and renamed to .MainFrame

+
+    Only recorded if the page has at least one identified ad frame. Bytes are
+    measured as over-the-wire (e.g., compressed) response body KBs and does not

[Ilya Sherman, 2017/04/26 00:09:45]

nit: The comment about bytes seems irrelevant to this histogram.

[jkarlin, 2017/04/26 16:34:54]

Done.

+    include header bytes. An ad frame consists of the identified ad frame and
+    all of its children (which may also be ads, but are counted as part of the
+    ancestor ad frame).
+  </summary>
+</histogram>
+
+<histogram name="PageLoad.Clients.Ads.Google.AdFrameRenavigatedToAd"
+    units="Boolean">

[Ilya Sherman, 2017/04/26 00:09:44]

nit: (Just within this file), please define a custom enum with more semantically
rich labels.

[jkarlin, 2017/04/26 16:34:54]

Done.

+  <owner>jkarlin@chromium.org</owner>
+  <summary>
+    When a frame that is (or previously was) an ad frame renavigates, record
+    whether it renavigated to an ad frame or a non-ad frame.
+
+    An ad frame consists of the identified ad frame and all of its children. Its
+    children (which may also be ads) are not counted when they renavigate.
+  </summary>
+</histogram>
+
+<histogram name="PageLoad.Clients.Ads.Google.Bytes.AllAdFrames.Network"
+    units="KB">

[Ilya Sherman, 2017/04/26 00:09:44]

Could you use a histogram_suffixes element (or a sequence of them) to reduce the
amount of repeated text among these histograms?  You'll likely find the
base="true" attribute useful.

[jkarlin, 2017/04/26 16:34:54]

I think suffixes will make these much harder to review and maintain. I have a
strong preference to keep these as is.

Eventually there is a good chance that we'll want to have Clients.Ads.* and
Clients.Ads.Google.* at which point I think breaking into suffixes will make
sense.

+  <owner>jkarlin@chromium.org</owner>
+  <summary>
+    The size (in KB) of the resources loaded for all of the ad frames on the
+    page that loaded over the network.
+
+    Only recorded if the page has at least one identified ad frame. Bytes are
+    measured as over-the-wire (e.g., compressed) response body KBs and does not
+    include header bytes. An ad frame consists of the identified ad frame and
+    all of its children (which may also be ads, but are counted as part of the
+    ancestor ad frame).
+  </summary>
+</histogram>
+
+<histogram name="PageLoad.Clients.Ads.Google.Bytes.AllAdFrames.Total"
+    units="KB">
+  <owner>jkarlin@chromium.org</owner>
+  <summary>
+    The size (in KB) of the resources loaded for all of the ad frames on the
+    page.
+
+    Only recorded if the page has at least one identified ad frame. Bytes are
+    measured as over-the-wire (e.g., compressed) response body KBs and does not
+    include header bytes. An ad frame consists of the identified ad frame and
+    all of its children (which may also be ads, but are counted as part of the
+    ancestor ad frame).
+  </summary>
+</histogram>
+
+<histogram name="PageLoad.Clients.Ads.Google.Bytes.Network" units="KB">
+  <owner>jkarlin@chromium.org</owner>
+  <summary>
+    The size (in KB) of all of the page's resources that loaded over the
+    network.
+
+    Only recorded if the page has at least one identified ad frame. Bytes are
+    measured as over-the-wire (e.g., compressed) response body KBs and does not
+    include header bytes. An ad frame consists of the identified ad frame and
+    all of its children (which may also be ads, but are counted as part of the
+    ancestor ad frame).
+  </summary>
+</histogram>
+
+<histogram name="PageLoad.Clients.Ads.Google.Bytes.NonAdFrames.Total"
+    units="KB">
+  <owner>jkarlin@chromium.org</owner>
+  <summary>
+    The size (in KB) of all of the page's resources except for those loaded in
+    ad frames.
+
+    Only recorded if the page has at least one identified ad frame. Bytes are
+    measured as over-the-wire (e.g., compressed) response body KBs and does not
+    include header bytes. An ad frame consists of the identified ad frame and
+    all of its children (which may also be ads, but are counted as part of the
+    ancestor ad frame).
+  </summary>
+</histogram>
+
+<histogram name="PageLoad.Clients.Ads.Google.Bytes.PerAdFrame.Network"
+    units="KB">
+  <owner>jkarlin@chromium.org</owner>
+  <summary>
+    The size (in KB) of the resources loaded for an ad frame from the network.
+
+    Only recorded if the page has at least one identified ad frame. Bytes are
+    measured as over-the-wire (e.g., compressed) response body KBs and does not
+    include header bytes. An ad frame consists of the identified ad frame and
+    all of its children (which may also be ads, but are counted as part of the
+    ancestor ad frame).
+  </summary>
+</histogram>
+
+<histogram name="PageLoad.Clients.Ads.Google.Bytes.PerAdFrame.Total" units="KB">
+  <owner>jkarlin@chromium.org</owner>
+  <summary>
+    The size (in KB) of the resources loaded for an ad frame.
+
+    Only recorded if the page has at least one identified ad frame. Bytes are
+    measured as over-the-wire (e.g., compressed) response body KBs and does not
+    include header bytes. An ad frame consists of the identified ad frame and
+    all of its children (which may also be ads, but are counted as part of the
+    ancestor ad frame).
+  </summary>
+</histogram>
+
+<histogram name="PageLoad.Clients.Ads.Google.Bytes.PercentAdFrame.Network"
+    units="%">
+  <owner>jkarlin@chromium.org</owner>
+  <summary>
+    The percentage of bytes loaded for a single ad frame that were loaded over
+    the network.
+
+    Only recorded if the page has at least one identified ad frame. Bytes are
+    measured as over-the-wire (e.g., compressed) response body KBs and does not
+    include header bytes. An ad frame consists of the identified ad frame and
+    all of its children (which may also be ads, but are counted as part of the
+    ancestor ad frame).
+  </summary>
+</histogram>
+
+<histogram name="PageLoad.Clients.Ads.Google.Bytes.PercentAllAdFrames.Network"
+    units="%">
+  <owner>jkarlin@chromium.org</owner>
+  <summary>
+    The percentage of bytes loaded for all ad frames that were loaded over the
+    network.
+
+    Only recorded if the page has at least one identified ad frame. Bytes are
+    measured as over-the-wire (e.g., compressed) response body KBs and does not
+    include header bytes. An ad frame consists of the identified ad frame and
+    all of its children (which may also be ads, but are counted as part of the
+    ancestor ad frame).
+  </summary>
+</histogram>
+
+<histogram
+    name="PageLoad.Clients.Ads.Google.Bytes.PercentPage.AllAdFrames.Network"
+    units="%">
+  <owner>jkarlin@chromium.org</owner>
+  <summary>
+    The percentage of bytes loaded for the page (from the network) that came
+    from resource loads in ad frames (from the network).
+
+    Only recorded if the page has at least one identified ad frame. Bytes are
+    measured as over-the-wire (e.g., compressed) response body KBs and does not
+    include header bytes. An ad frame consists of the identified ad frame and
+    all of its children (which may also be ads, but are counted as part of the
+    ancestor ad frame).
+  </summary>
+</histogram>
+
+<histogram
+    name="PageLoad.Clients.Ads.Google.Bytes.PercentPage.AllAdFrames.Total"
+    units="%">
+  <owner>jkarlin@chromium.org</owner>
+  <summary>
+    The percentage of bytes loaded for the page that came from resource loads in
+    ad frames.
+
+    Only recorded if the page has at least one identified ad frame. Bytes are
+    measured as over-the-wire (e.g., compressed) response body KBs and does not
+    include header bytes. An ad frame consists of the identified ad frame and
+    all of its children (which may also be ads, but are counted as part of the
+    ancestor ad frame). The percentage of the page's prefiltered (e.g.,
+    compressed) response body KB loaded from frames (and their child frames)
+    identified as Google Ad Frames.
+  </summary>
+</histogram>
+
+<histogram name="PageLoad.Clients.Ads.Google.Bytes.Total" units="KB">
+  <owner>jkarlin@chromium.org</owner>
+  <summary>
+    The size (in KB) of all of the page's resources.
+
+    Only recorded if the page has at least one identified ad frame. Bytes are
+    measured as over-the-wire (e.g., compressed) response body KBs and does not
+    include header bytes. An ad frame consists of the identified ad frame and
+    all of its children (which may also be ads, but are counted as part of the
+    ancestor ad frame).
+  </summary>
+</histogram>
+
+<histogram name="PageLoad.Clients.Ads.Google.NonAdFrameRenavigatedToAd"
+    units="Boolean">

[Ilya Sherman, 2017/04/26 00:09:44]

Ditto about the enum.

[jkarlin, 2017/04/26 16:34:54]

Done.

+  <owner>jkarlin@chromium.org</owner>
+  <summary>
+    When a frame that has never been part of an ad frame renavigates, record
+    whether it renavigated to an ad frame or a non-ad frame.

[Ilya Sherman, 2017/04/26 00:09:44]

Is this metric only recorded if the page originally had an ad on it?  The
description for "PageLoad.Clients.Ads.Google.AdFrameCount" suggests the answer
is yes; but the lack of text to this effect makes me ask, since the other
histograms are all careful to reiterate this.

[jkarlin, 2017/04/26 16:34:54]

Good question. This metric is a special case. Updated the text.

+  </summary>
+</histogram>
+
+<histogram
+    name="PageLoad.Clients.Ads.Google.PercentSubFramesAreAdFrames.TopLevel"
+    units="%">
+  <owner>jkarlin@chromium.org</owner>
+  <summary>
+    The percentage of top-level frames on the page that are identified as Google
+    Ad Frames.
+
+    Only recorded if the page has at least one identified ad frame. Bytes are
+    measured as over-the-wire (e.g., compressed) response body KBs and does not
+    include header bytes. An ad frame consists of the identified ad frame and
+    all of its children (which may also be ads, but are counted as part of the
+    ancestor ad frame).
+  </summary>
+</histogram>
+
+<histogram name="PageLoad.Clients.Ads.Google.SubFrameCount.TopLevel"
+    units="Frames">
+  <owner>jkarlin@chromium.org</owner>
+  <summary>
+    The number of top-level frames on the page.
+
+      Only recorded if the page has at least one identified ad frame. Bytes are

[Ilya Sherman, 2017/04/26 00:09:44]

nit: Whitespace

[jkarlin, 2017/04/26 16:34:54]

Done.

+    measured as over-the-wire (e.g., compressed) response body KBs and does not
+    include header bytes. An ad frame consists of the identified ad frame and
+    all of its children (which may also be ads, but are counted as part of the
+    ancestor ad frame).
+  </summary>
+</histogram>
+
 <histogram
     name="PageLoad.Clients.DataReductionProxy.Experimental.Bytes.Network.CompressionRatio"
     units="%">