Document that 'never' is valid for expires_after in rare cases.

Bug: 923083
Change-Id: Ic774c0bda4ce2f0fb794923d31c92511fabc76cb
Reviewed-on: https://chromium-review.googlesource.com/c/1447845
Commit-Queue: Brian White <bcwhite@chromium.org>
Reviewed-by: Alexei Svitkine <asvitkine@chromium.org>
Cr-Commit-Position: refs/heads/master@{#630047}

tools/metrics/histograms/README.md

@@ -282,6 +282,16 @@ histogram would remain useful, the expiration should be extended accordingly
 before it becomes expired. If histogram you care about already expired, see
 [Expired Histogram Whitelist](#Expired-histogram-whitelist).
 
+In **rare** cases, the expiry can be set to "never". This is used to denote
+metrics of critical importance that are, typically, used for other reports.
+For example, all metrics of the "[heartbeat](https://uma.googleplex.com/p/chrome/variations)"
+are set to never expire.  All metrics that never expire must have an XML
+comment describing why so that it can be audited in the future.
+
+```
+<!-- expires-never: "heartbeat" metric (internal: go/uma-heartbeats) -->
+```
+
 For all the new histograms the use of expiry attribute will be strongly
 encouraged and enforced by Chrome metrics team through reviews.
 

tools/metrics/histograms/histograms.xml

@@ -29550,7 +29550,7 @@ uploading your change for review.
 
 <histogram name="Event.Latency.ScrollBegin.Touch.TimeToScrollUpdateSwapBegin4"
     units="microseconds" expires_after="never">
-<!-- expires-never: "heartbeat" metric -->
+<!-- expires-never: "heartbeat" metric (internal: go/uma-heartbeats) -->
 
   <owner>tdresser@chromium.org</owner>
   <owner>input-dev@chromium.org</owner>
@@ -29701,7 +29701,7 @@ uploading your change for review.
 
 <histogram name="Event.Latency.ScrollBegin.Wheel.TimeToScrollUpdateSwapBegin4"
     units="microseconds" expires_after="never">
-<!-- expires-never: "heartbeat" metric -->
+<!-- expires-never: "heartbeat" metric (internal: go/uma-heartbeats) -->
 
   <owner>tdresser@chromium.org</owner>
   <summary>
@@ -29820,7 +29820,7 @@ uploading your change for review.
 <histogram
     name="Event.Latency.ScrollInertial.Touch.TimeToScrollUpdateSwapBegin4"
     units="microseconds" expires_after="never">
-<!-- expires-never: "heartbeat" metric -->
+<!-- expires-never: "heartbeat" metric (internal: go/uma-heartbeats) -->
 
   <owner>sahel@chromium.org</owner>
   <summary>
@@ -30077,7 +30077,7 @@ uploading your change for review.
 
 <histogram name="Event.Latency.ScrollUpdate.Touch.TimeToScrollUpdateSwapBegin4"
     units="microseconds" expires_after="never">
-<!-- expires-never: "heartbeat" metric -->
+<!-- expires-never: "heartbeat" metric (internal: go/uma-heartbeats) -->
 
   <owner>tdresser@chromium.org</owner>
   <owner>input-dev@chromium.org</owner>
@@ -30261,7 +30261,7 @@ uploading your change for review.
 
 <histogram name="Event.Latency.ScrollUpdate.Wheel.TimeToScrollUpdateSwapBegin4"
     units="microseconds" expires_after="never">
-<!-- expires-never: "heartbeat" metric -->
+<!-- expires-never: "heartbeat" metric (internal: go/uma-heartbeats) -->
 
   <owner>tdresser@chromium.org</owner>
   <summary>
@@ -51183,7 +51183,7 @@ uploading your change for review.
 
 <histogram name="Memory.AudioService.PrivateMemoryFootprint" units="MB"
     expires_after="never">
-<!-- expires-never: "heartbeat" metric -->
+<!-- expires-never: "heartbeat" metric (internal: go/uma-heartbeats) -->
 
   <owner>marinaciocea@chromium.org</owner>
   <owner>maxmorin@chromium.org</owner>
@@ -51286,7 +51286,7 @@ uploading your change for review.
 
 <histogram name="Memory.Browser.PrivateMemoryFootprint" units="MB"
     expires_after="never">
-<!-- expires-never: "heartbeat" metric -->
+<!-- expires-never: "heartbeat" metric (internal: go/uma-heartbeats) -->
 
   <owner>erikchen@chromium.org</owner>
   <summary>
@@ -52089,7 +52089,7 @@ uploading your change for review.
 
 <histogram name="Memory.Extension.PrivateMemoryFootprint" units="MB"
     expires_after="never">
-<!-- expires-never: "heartbeat" metric -->
+<!-- expires-never: "heartbeat" metric (internal: go/uma-heartbeats) -->
 
   <owner>erikchen@chromium.org</owner>
   <owner>ssid@chromium.org</owner>
@@ -52163,7 +52163,7 @@ uploading your change for review.
 
 <histogram name="Memory.Gpu.PrivateMemoryFootprint" units="MB"
     expires_after="never">
-<!-- expires-never: "heartbeat" metric -->
+<!-- expires-never: "heartbeat" metric (internal: go/uma-heartbeats) -->
 
   <owner>erikchen@chromium.org</owner>
   <owner>ssid@chromium.org</owner>
@@ -52632,7 +52632,7 @@ uploading your change for review.
 
 <histogram name="Memory.Renderer.PrivateMemoryFootprint" units="MB"
     expires_after="never">
-<!-- expires-never: "heartbeat" metric -->
+<!-- expires-never: "heartbeat" metric (internal: go/uma-heartbeats) -->
 
   <owner>erikchen@chromium.org</owner>
   <owner>ssid@chromium.org</owner>
@@ -53266,7 +53266,7 @@ uploading your change for review.
 
 <histogram name="Memory.Total.PrivateMemoryFootprint" units="MB"
     expires_after="never">
-<!-- expires-never: "heartbeat" metric -->
+<!-- expires-never: "heartbeat" metric (internal: go/uma-heartbeats) -->
 
   <owner>erikchen@chromium.org</owner>
   <owner>ssid@chromium.org</owner>
@@ -53334,7 +53334,7 @@ uploading your change for review.
 
 <histogram name="Memory.Utility.PrivateMemoryFootprint" units="MB"
     expires_after="never">
-<!-- expires-never: "heartbeat" metric -->
+<!-- expires-never: "heartbeat" metric (internal: go/uma-heartbeats) -->
 
   <owner>jam@chromium.org</owner>
   <summary>
@@ -70056,7 +70056,7 @@ uploading your change for review.
 </histogram>
 
 <histogram name="NewTabPage.LoadTime" units="ms" expires_after="never">
-<!-- expires-never: "heartbeat" metric -->
+<!-- expires-never: "heartbeat" metric (internal: go/uma-heartbeats) -->
 
   <owner>treib@chromium.org</owner>
   <summary>
@@ -74690,7 +74690,7 @@ uploading your change for review.
 
 <histogram name="Omnibox.CharTypedToRepaintLatency" units="ms"
     expires_after="never">
-<!-- expires-never: "heartbeat" metric -->
+<!-- expires-never: "heartbeat" metric (internal: go/uma-heartbeats) -->
 
   <owner>asvitkine@chromium.org</owner>
   <owner>mpearson@chromium.org</owner>
@@ -78871,7 +78871,7 @@ uploading your change for review.
 
 <histogram name="PageLoad.PaintTiming.ForegroundToFirstContentfulPaint"
     units="ms" expires_after="never">
-<!-- expires-never: "heartbeat" metric -->
+<!-- expires-never: "heartbeat" metric (internal: go/uma-heartbeats) -->
 
   <owner>speed-metrics-dev@chromium.org</owner>
   <summary>
@@ -78882,7 +78882,7 @@ uploading your change for review.
 
 <histogram name="PageLoad.PaintTiming.ForegroundToFirstPaint" units="ms"
     expires_after="never">
-<!-- expires-never: "heartbeat" metric -->
+<!-- expires-never: "heartbeat" metric (internal: go/uma-heartbeats) -->
 
   <owner>speed-metrics-dev@chromium.org</owner>
   <summary>
@@ -78893,7 +78893,7 @@ uploading your change for review.
 
 <histogram name="PageLoad.PaintTiming.NavigationToFirstContentfulPaint"
     units="ms" expires_after="never">
-<!-- expires-never: "heartbeat" metric -->
+<!-- expires-never: "heartbeat" metric (internal: go/uma-heartbeats) -->
 
   <owner>ksakamoto@chromium.org</owner>
   <owner>speed-metrics-dev@chromium.org</owner>
@@ -78907,7 +78907,7 @@ uploading your change for review.
 
 <histogram name="PageLoad.PaintTiming.NavigationToFirstImagePaint" units="ms"
     expires_after="never">
-<!-- expires-never: "heartbeat" metric -->
+<!-- expires-never: "heartbeat" metric (internal: go/uma-heartbeats) -->
 
   <owner>speed-metrics-dev@chromium.org</owner>
   <summary>
@@ -78919,7 +78919,7 @@ uploading your change for review.
 
 <histogram name="PageLoad.PaintTiming.NavigationToFirstPaint" units="ms"
     expires_after="never">
-<!-- expires-never: "heartbeat" metric -->
+<!-- expires-never: "heartbeat" metric (internal: go/uma-heartbeats) -->
 
   <owner>ksakamoto@chromium.org</owner>
   <owner>speed-metrics-dev@chromium.org</owner>
@@ -78945,7 +78945,7 @@ uploading your change for review.
 
 <histogram name="PageLoad.PaintTiming.ParseStartToFirstContentfulPaint"
     units="ms" expires_after="never">
-<!-- expires-never: "heartbeat" metric -->
+<!-- expires-never: "heartbeat" metric (internal: go/uma-heartbeats) -->
 
   <owner>bmcquade@chromium.org</owner>
   <owner>csharrison@chromium.org</owner>
@@ -100169,7 +100169,7 @@ uploading your change for review.
 
 <histogram name="Scheduling.Renderer.DrawInterval2" units="microseconds"
     expires_after="never">
-<!-- expires-never: "heartbeat" metric -->
+<!-- expires-never: "heartbeat" metric (internal: go/uma-heartbeats) -->
 
   <owner>vmiura@chromium.org</owner>
   <owner>sadrul@chromium.org</owner>
@@ -105001,7 +105001,7 @@ uploading your change for review.
 
 <histogram name="SessionRestore.ForegroundTabFirstPaint3" units="ms"
     expires_after="never">
-<!-- expires-never: "heartbeat" metric -->
+<!-- expires-never: "heartbeat" metric (internal: go/uma-heartbeats) -->
 
   <owner>chrisha@chromium.org</owner>
   <owner>georgesak@chromium.org</owner>
@@ -111808,7 +111808,7 @@ uploading your change for review.
 
 <histogram name="Startup.FirstWebContents.NonEmptyPaint2" units="ms"
     expires_after="never">
-<!-- expires-never: "heartbeat" metric -->
+<!-- expires-never: "heartbeat" metric (internal: go/uma-heartbeats) -->
 
   <owner>fdoray@chromium.org</owner>
   <owner>gab@chromium.org</owner>