Histogram Documentation - Clarity UMA Sampling Rate Histogram

Bug: 832926
Change-Id: I2be0237188ebfd7cf15e60f9187bff7deb8ef8fe
Reviewed-on: https://chromium-review.googlesource.com/c/chromium/src/+/1831465
Commit-Queue: Mark Pearson <mpearson@chromium.org>
Auto-Submit: Mark Pearson <mpearson@chromium.org>
Reviewed-by: Jesse Doherty <jwd@chromium.org>
Cr-Commit-Position: refs/heads/master@{#702543}

tools/metrics/histograms/histograms.xml

@@ -150650,13 +150650,31 @@ should be kept until we use this API.  -->
   </summary>
 </histogram>
 
-<histogram name="UMA.SamplingRatePerMille" units="samples permille"
+<histogram name="UMA.SamplingRatePerMille" units="samples per mille"
     expires_after="M81">
   <owner>jwd@chromium.org</owner>
   <owner>src/base/metrics/OWNERS</owner>
   <summary>
     Sample rate applied to this client, expressed as number of clients per 1000
-    that are in the sample. Recorded on every log upload.
+    that are in the sample. Recorded on every log upload but only if the client
+    is eligible for sampling. (As of September 2019, the only clients eligible
+    for sampling are Windows and Android installs on which the UMA checkbox was
+    enabled by default.)
+
+    Clients not eligible for sampling will not have this histogram recorded.
+
+    Clients that are eligible for sampling but are sampled out (i.e., not
+    uploading logs) will not have this histogram recorded. Notably, it will not
+    appear in chrome://histograms! (Obviously, it also won't appear in the UMA
+    logs because the client is not uploading logs.)
+
+    Additional nuance, hopefully not important: the rate refers to the session
+    that the log was generated in, not the session the log was generated about.
+    This means when UMA uploads information about the last session (such as
+    stability statistics), it is possible--though extremely unlikely--that the
+    sampling rate config has changed from the previous session to the current
+    one. As such, the sampling rate emitted in a previous-session log record may
+    not be the right one that should've applied to that record.
   </summary>
 </histogram>