Update descriptions and owners for permissions metrics.

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 78740b931d6abe68c88fb1a254ccfa9abb1e29c1..08d84e378b729437ed8ca61f7f5b1dec8a044f1c 100644
--- a/tools/metrics/histograms/histograms.xml
+++ b/tools/metrics/histograms/histograms.xml
@@ -6892,23 +6892,70 @@ http://cs/file:chrome/histograms.xml - but prefer this file for new entries.
 </histogram>
 
 <histogram name="ContentSettings.PermissionRequested" enum="PermissionType">
+  <owner>kcarattini@chromium.org</owner>
+  <owner>dominickn@chromium.org</owner>
   <owner>miguelg@chromium.org</owner>
-  <summary>Number of times a given permission was requested.</summary>
+  <summary>
+    Number of times a given permission was requested by a website and the user
+    has the permission set to prompt (i.e. not blocked or allowed).
+
+    Note this is probably not the metric you want - it does not correspond to
+    the total number of times websites request a permission. Also, because
+    specific permissions have code that can automatically block or grant
+    permissions based on things like incognito, installed extensions etc., this
+    does also not correspond to the number of times users are prompted to allow
+    permissions.
+
+    For a better metric to track how often users are prompted, either use
+    ContentSettings.PermissionsActions*, or Permissions.Prompt.*.
+
+    See https://crbug.com/638076 for more details.
+  </summary>
 </histogram>
 
 <histogram name="ContentSettings.PermissionRequested_InsecureOrigin"
     enum="PermissionType">
+  <owner>kcarattini@chromium.org</owner>
+  <owner>dominickn@chromium.org</owner>
   <owner>miguelg@chromium.org</owner>
   <summary>
-    Number of times a given permission was requested from an insecure origin.
+    Number of times a given permission was requested by an insecure origin and
+    the user has the permission set to prompt (i.e. not blocked or allowed).
+
+    Note this is probably not the metric you want - it does not correspond to
+    the total number of times websites request a permission. Also, because
+    specific permissions have code that can automatically block or grant
+    permissions based on things like incognito, installed extensions etc., this
+    does also not correspond to the number of times users are prompted to allow
+    permissions.
+
+    For a better metric to track how often users are prompted, use
+    ContentSettings.PermissionsActions*.
+
+    See https://crbug.com/638076 for more details.
   </summary>
 </histogram>
 
 <histogram name="ContentSettings.PermissionRequested_SecureOrigin"
     enum="PermissionType">
+  <owner>kcarattini@chromium.org</owner>
+  <owner>dominickn@chromium.org</owner>
   <owner>miguelg@chromium.org</owner>
   <summary>
-    Number of times a given permission was requested from a secure origin.
+    Number of times a given permission was requested by a secure origin and the
+    user has the permission set to prompt (i.e. not blocked or allowed).
+
+    Note this is probably not the metric you want - it does not correspond to
+    the total number of times websites request a permission. Also, because
+    specific permissions have code that can automatically block or grant
+    permissions based on things like incognito, installed extensions etc., this
+    does also not correspond to the number of times users are prompted to allow
+    permissions.
+
+    For a better metric to track how often users are prompted, use
+    ContentSettings.PermissionsActions*.
+
+    See https://crbug.com/638076 for more details.
   </summary>
 </histogram>
 
@@ -41071,6 +41118,8 @@ http://cs/file:chrome/histograms.xml - but prefer this file for new entries.
 </histogram>
 
 <histogram name="Permissions.Action" enum="PermissionAction">
+  <owner>dominickn@chromium.org</owner>
+  <owner>kcarattini@chromium.org</owner>
   <owner>miguelg@chromium.org</owner>
   <owner>mlamouri@chromium.org</owner>
   <summary>
@@ -41080,6 +41129,8 @@ http://cs/file:chrome/histograms.xml - but prefer this file for new entries.
 </histogram>
 
 <histogram name="Permissions.Action.InsecureOrigin" enum="PermissionAction">
+  <owner>dominickn@chromium.org</owner>
+  <owner>kcarattini@chromium.org</owner>
   <owner>miguelg@chromium.org</owner>
   <owner>mlamouri@chromium.org</owner>
   <summary>
@@ -41089,6 +41140,8 @@ http://cs/file:chrome/histograms.xml - but prefer this file for new entries.
 </histogram>
 
 <histogram name="Permissions.Action.SecureOrigin" enum="PermissionAction">
+  <owner>dominickn@chromium.org</owner>
+  <owner>kcarattini@chromium.org</owner>
   <owner>miguelg@chromium.org</owner>
   <owner>mlamouri@chromium.org</owner>
   <summary>
@@ -41098,8 +41151,8 @@ http://cs/file:chrome/histograms.xml - but prefer this file for new entries.
 </histogram>
 
 <histogram name="Permissions.Prompt.Accepted" enum="PermissionRequestType">
-  <owner>benwells@chromium.org</owner>
-  <owner>tsergeant@chromium.org</owner>
+  <owner>dominickn@chromium.org</owner>
+  <owner>kcarattini@chromium.org</owner>
   <summary>
     Tracks the permission bubbles (merged and non-merged) that are accepted.
     Merged bubbles are considered accepted if all permissions are allowed.
@@ -41108,6 +41161,7 @@ http://cs/file:chrome/histograms.xml - but prefer this file for new entries.
 
 <histogram name="Permissions.Prompt.Accepted.Persisted" enum="BooleanPersisted">
   <owner>dominickn@chromium.org</owner>
+  <owner>kcarattini@chromium.org</owner>
   <summary>
     For each granted permission prompt displayed with a persistence toggle
     (remember my decision), records whether the persistence toggle was enabled
@@ -41117,6 +41171,7 @@ http://cs/file:chrome/histograms.xml - but prefer this file for new entries.
 
 <histogram name="Permissions.Prompt.Accepted.PriorDismissCount">
   <owner>dominickn@chromium.org</owner>
+  <owner>kcarattini@chromium.org</owner>
   <summary>
     This metric, recorded at the time of a permission prompt accept, records the
     total number of prompt dismissal events for this origin since the last time
@@ -41127,6 +41182,7 @@ http://cs/file:chrome/histograms.xml - but prefer this file for new entries.
 
 <histogram name="Permissions.Prompt.Accepted.PriorIgnoreCount">
   <owner>dominickn@chromium.org</owner>
+  <owner>kcarattini@chromium.org</owner>
   <summary>
     This metric, recorded at the time of a permission prompt accept, records the
     total number of prompt ignore events for this origin since the last time the
@@ -41136,8 +41192,8 @@ http://cs/file:chrome/histograms.xml - but prefer this file for new entries.
 </histogram>
 
 <histogram name="Permissions.Prompt.Denied" enum="PermissionRequestType">
-  <owner>benwells@chromium.org</owner>
-  <owner>tsergeant@chromium.org</owner>
+  <owner>dominickn@chromium.org</owner>
+  <owner>kcarattini@chromium.org</owner>
   <summary>
     Tracks the permission bubbles (merged and non-merged) that are denied.
     Merged bubbles are considered denied if any permission is denied.
@@ -41146,6 +41202,7 @@ http://cs/file:chrome/histograms.xml - but prefer this file for new entries.
 
 <histogram name="Permissions.Prompt.Denied.Persisted" enum="BooleanPersisted">
   <owner>dominickn@chromium.org</owner>
+  <owner>kcarattini@chromium.org</owner>
   <summary>
     For each denied permission prompt displayed with a persistence toggle
     (remember my decision), records whether the persistence toggle was enabled
@@ -41155,6 +41212,7 @@ http://cs/file:chrome/histograms.xml - but prefer this file for new entries.
 
 <histogram name="Permissions.Prompt.Denied.PriorDismissCount">
   <owner>dominickn@chromium.org</owner>
+  <owner>kcarattini@chromium.org</owner>
   <summary>
     This metric, recorded at the time of a permission prompt deny, records the
     total number of prompt dismissal events for this origin since the last time
@@ -41165,6 +41223,7 @@ http://cs/file:chrome/histograms.xml - but prefer this file for new entries.
 
 <histogram name="Permissions.Prompt.Denied.PriorIgnoreCount">
   <owner>dominickn@chromium.org</owner>
+  <owner>kcarattini@chromium.org</owner>
   <summary>
     This metric, recorded at the time of a permission prompt deny, records the
     total number of prompt ignore events for this origin since the last time the
@@ -41175,6 +41234,7 @@ http://cs/file:chrome/histograms.xml - but prefer this file for new entries.
 
 <histogram name="Permissions.Prompt.DismissCount">
   <owner>dominickn@chromium.org</owner>
+  <owner>kcarattini@chromium.org</owner>
   <obsolete>
     Renamed to Permissions.Prompt.Dismissed.PriorDismissCount on 17 August 2016.
   </obsolete>
@@ -41190,6 +41250,7 @@ http://cs/file:chrome/histograms.xml - but prefer this file for new entries.
 
 <histogram name="Permissions.Prompt.Dismissed.PriorDismissCount">
   <owner>dominickn@chromium.org</owner>
+  <owner>kcarattini@chromium.org</owner>
   <summary>
     This metric, recorded at the time of a permission prompt dismiss, records
     the total number of prompt dismissal events for this origin since the last
@@ -41200,6 +41261,7 @@ http://cs/file:chrome/histograms.xml - but prefer this file for new entries.
 
 <histogram name="Permissions.Prompt.Dismissed.PriorIgnoreCount">
   <owner>dominickn@chromium.org</owner>
+  <owner>kcarattini@chromium.org</owner>
   <summary>
     This metric, recorded at the time of a permission prompt dismiss, records
     the total number of prompt ignore events for this origin since the last time
@@ -41210,6 +41272,7 @@ http://cs/file:chrome/histograms.xml - but prefer this file for new entries.
 
 <histogram name="Permissions.Prompt.IgnoreCount">
   <owner>dominickn@chromium.org</owner>
+  <owner>kcarattini@chromium.org</owner>
   <obsolete>
     Renamed to Permissions.Prompt.Dismissed.PriorDismissCount on 17 August 2016.
   </obsolete>
@@ -41225,6 +41288,7 @@ http://cs/file:chrome/histograms.xml - but prefer this file for new entries.
 
 <histogram name="Permissions.Prompt.Ignored.PriorDismissCount">
   <owner>dominickn@chromium.org</owner>
+  <owner>kcarattini@chromium.org</owner>
   <summary>
     This metric, recorded at the time of a permission prompt ignore, records the
     total number of prompt dismissal events for this origin since the last time
@@ -41235,6 +41299,7 @@ http://cs/file:chrome/histograms.xml - but prefer this file for new entries.
 
 <histogram name="Permissions.Prompt.Ignored.PriorIgnoreCount">
   <owner>dominickn@chromium.org</owner>
+  <owner>kcarattini@chromium.org</owner>
   <summary>
     This metric, recorded at the time of a permission prompt ignore, records the
     total number of prompt ignore events for this origin since the last time the
@@ -41245,8 +41310,8 @@ http://cs/file:chrome/histograms.xml - but prefer this file for new entries.
 
 <histogram name="Permissions.Prompt.MergedBubbleAccepted"
     enum="PermissionRequestType">
-  <owner>benwells@chromium.org</owner>
-  <owner>tsergeant@chromium.org</owner>
+  <owner>dominickn@chromium.org</owner>
+  <owner>kcarattini@chromium.org</owner>
   <summary>
     Tracks acceptance of permission bubble request types that have been merged
     into coalesced bubbles.
@@ -41255,8 +41320,8 @@ http://cs/file:chrome/histograms.xml - but prefer this file for new entries.
 
 <histogram name="Permissions.Prompt.MergedBubbleDenied"
     enum="PermissionRequestType">
-  <owner>benwells@chromium.org</owner>
-  <owner>tsergeant@chromium.org</owner>
+  <owner>dominickn@chromium.org</owner>
+  <owner>kcarattini@chromium.org</owner>
   <summary>
     Tracks denial of permission bubble request types that have been merged into
     coalesced bubbles.
@@ -41265,8 +41330,8 @@ http://cs/file:chrome/histograms.xml - but prefer this file for new entries.
 
 <histogram name="Permissions.Prompt.MergedBubbleTypes"
     enum="PermissionRequestType">
-  <owner>benwells@chromium.org</owner>
-  <owner>tsergeant@chromium.org</owner>
+  <owner>dominickn@chromium.org</owner>
+  <owner>kcarattini@chromium.org</owner>
   <summary>
     Tracks the permission bubble request types that are being merged into
     coalesced bubbles.
@@ -41274,8 +41339,8 @@ http://cs/file:chrome/histograms.xml - but prefer this file for new entries.
 </histogram>
 
 <histogram name="Permissions.Prompt.RequestsPerPrompt">
-  <owner>benwells@chromium.org</owner>
-  <owner>tsergeant@chromium.org</owner>
+  <owner>dominickn@chromium.org</owner>
+  <owner>kcarattini@chromium.org</owner>
   <summary>
     How many permission requests each permissions prompt shown to the user
     contains.
@@ -41283,29 +41348,57 @@ http://cs/file:chrome/histograms.xml - but prefer this file for new entries.
 </histogram>
 
 <histogram name="Permissions.Prompt.Shown" enum="PermissionRequestType">
-  <owner>benwells@chromium.org</owner>
-  <owner>tsergeant@chromium.org</owner>
+  <owner>dominickn@chromium.org</owner>
+  <owner>kcarattini@chromium.org</owner>
   <summary>
     Tracks how many times permission prompts are shown to users.
   </summary>
 </histogram>
 
 <histogram name="Permissions.Requested.CrossOrigin" enum="PermissionStatus">
+  <owner>dominickn@chromium.org</owner>
+  <owner>kcarattini@chromium.org</owner>
   <owner>keenanb@google.com</owner>
   <owner>jww@chromium.org</owner>
   <summary>
     The embedder's permission setting at the time of a cross-origin iframe
     permission request for a given permission type. See the corresponding
     histogram suffixes.
+
+    A request is when a website makes a permission request and the user has the
+    permission set to prompt (i.e. not blocked or allowed).
+
+    Note this is probably not the metric you want - it does not correspond to
+    the total number of times websites request a permission. Also, because
+    specific permissions have code that can automatically block or grant
+    permissions based on things like incognito, installed extensions etc., this
+    does also not correspond to the number of times users are prompted to allow
+    permissions.
+
+    See https://crbug.com/638076 for more details.
   </summary>
 </histogram>
 
 <histogram name="Permissions.Requested.SameOrigin" enum="PermissionType">
+  <owner>dominickn@chromium.org</owner>
+  <owner>kcarattini@chromium.org</owner>
   <owner>keenanb@google.com</owner>
   <owner>jww@chromium.org</owner>
   <summary>
     The permission type (geolocation, and such) of a same-origin permission
     request.
+
+    A request is when a website makes a permission request and the user has the
+    permission set to prompt (i.e. not blocked or allowed).
+
+    Note this is probably not the metric you want - it does not correspond to
+    the total number of times websites request a permission. Also, because
+    specific permissions have code that can automatically block or grant
+    permissions based on things like incognito, installed extensions etc., this
+    does also not correspond to the number of times users are prompted to allow
+    permissions.
+
+    See https://crbug.com/638076 for more details.
   </summary>
 </histogram>