Update README and one-pager doc

Update README and one-pager for the latest pattern histogram
instructions. Reuse/Remove some of the legacy histogram-suffixes docs.

Change-Id: I0bc63ea8d419c5ab861d5d64f39ecc150c6ad8b0
Reviewed-on: https://chromium-review.googlesource.com/c/chromium/src/+/2380344
Commit-Queue: Weilun Shi <sweilun@chromium.org>
Reviewed-by: Steven Holte <holte@chromium.org>
Auto-Submit: Weilun Shi <sweilun@chromium.org>
Cr-Commit-Position: refs/heads/master@{#803603}

tools/metrics/histograms/README.md

@@ -539,28 +539,29 @@ histogram at some point that did so even if it isn't active now.
 been recorded to. For example, it's fine to correct a typo where the histogram
 name in the metadata does not match the name in the Chromium source code.
 
-### Histogram Suffixes
+### Pattern histogram
 
 It is sometimes useful to record several closely related metrics, which measure
 the same type of data, with some minor variations. It is often useful to use one
-or more <histogram_suffixes> elements to save on redundant verbosity
-in [histograms.xml](./histograms.xml). If a root `<histogram>` or a `<suffix>`
-element is used only to construct a partial name, to be completed by further
-suffixes, annotate the element with the attribute `base="true"`. This instructs
-tools not to treat the partial base name as a distinct histogram. Note that
-suffixes can be applied recursively.
-
-You can also declare ownership of `<histogram_suffixes>`. If there's no owner
-specified, the generated histograms will inherit owners from the parents.
+or more <variants> elements to save on redundant verbosity in
+[histograms.xml](./histograms.xml). You can put the placeholder string in
+anywhere of the histogram name. Each placeholder string should associate with
+a single token based on the token's key. Each token can specify the `variants`
+attribute to associate with an out-of-line `<variants>` or declare a list of
+`<variant>`s as its children. These <variant>s will then replace the
+corresponding placeholder string in the histogram name to create a family of
+histograms.
+
+You can't declare ownership of `<variants>` but can declare ownership of
+`<variant>`. If there's no owner specified, the generated histograms will
+inherit owners from the parents.
 
 As [with histogram entries](#Cleaning-Up-Histogram-Entries), never delete
-histogram suffixes. If the suffix expansion is no longer used, mark it as
-obsolete.  You can also mark individual histograms within the suffix as
-obsolete, indicating the expansion for that histogram is obsolete yet the
-expansion for other histograms with the same suffix are not.
+variants. If the variant expansion is no longer used, mark it as
+obsolete.
 
-Histogram suffixes can be difficult to use, especially if they are applied
-recursively. Consider using the `print_histogram_names.py --diff` tool to
+If you feel unclear about which histograms will be generated from the pattern
+histogram. Consider using the `print_histogram_names.py --diff` tool to
 enumerate all the histogram names that are generated by a particular CL. e.g.
 (from the repo root):
 ```

tools/metrics/histograms/one-pager.md

@@ -31,11 +31,130 @@ the codebase; and the histogram definition should be marked as obsolete. However
 if the histogram would remain useful, the expiration should be extended
 accordingly. We recommend to always specify an expiry for new histograms.
 
-## Histogram suffixes
+## Pattern histogram
+
+Pattern histograms are a convenient way of describing a set of similar
+histograms. Placeholders are used in the <histogram> name and summary, which
+have substitutions described by <token> tags.  Each possible values is described
+by a <variant> tag, which may either be inline in the <token>, or described in a
+<variants> tag that can be referenced by <token>s.
+
+A `<variant>` may be marked obsolete, or specify explicit `<owner>`s that
+override the pattern's owners.
+
+If we define the following:
+
+```
+<variants name="OmniboxProviderVersion">
+  <variant name=".Provider" summary="old version">
+    <obsolete>
+  	Deprecated. Replaced by Provider2.
+    </obsolete>
+  </variant>
+  <variant name=".Provider2" summary="second version"/>
+</variants>
+
+<histogram name="Omnibox{version}{content}.Time" units="ms"
+  expires_after="2020-12-25">
+  <owner>me@chromium.org</owner>
+  <summary>
+    The length of time taken by the {version} of {content} provider's
+    synchronous pass.
+  </summary>
+  <token key="version" variants="OmniboxProviderVersion"/>
+  <token key="content">
+    <variant name=".All" summary="All"/>
+    <variant name=".ExtensionApp" summary="the ExtensionApp">
+      <owner>you@chromium.org</owner>
+    </variant>
+    <variant name=".HistoryContents" summary=" the HistoryContents"/>
+  </token>
+</histogram>
+```
+
+The complete list of histograms and their summary will be:
+
+```
+Omnibox.Provider.All.Time: The length of time taken by old versions of
+    All provider's synchronous pass. (obsolete)
+Omnibox.Provider.ExtensionApp.Time: The length of time taken by the old version
+    of the ExtensionApp provider's synchronous pass. (obsolete)
+Omnibox.Provider.HistoryContents.Time: The length of time taken by the old
+    version of the HistoryContents provider's synchronous pass. (obsolete)
+Omnibox.Provider2.All.Time: The length of time taken by the second version of
+    All provider's synchronous pass.
+Omnibox.Provider2.ExtensionApp.Time: The length of time taken by the second
+    version of the ExtensionApp provider's synchronous pass.
+Omnibox.Provider2.HistoryContents.Time: The length of time taken by the second
+    version of the HistoryContents provider's synchronous pass.
+```
+
+Among the above histograms, `Omnibox.Provider.ExtensionApp.Time` and
+`Omnibox.Provider2.ExtensionApp.Time` histograms belong to `you@chromium.org`
+whereas other histograms belong to `me@chromium.org`.
+
+The out-of-line variants can be shared between multiple histograms. Example:
+
+```
+<variants name="MyVariants">
+  <variant name=".V1" summary="V1"/>
+  <variant name=".V2" summary="V2"/>
+</variants>
+
+<histogram name="MyHist1{MyVaraints}">
+  <token key="MyVariants" varaints="MyVariants"/>
+</histogram>
+
+<histogram name="MyHist2{MyVaraints}">
+  <token key="MyVariants" varaints="MyVariants"/>
+</histogram>
+```
+
+The complete list of histograms will be:
+
+```
+MyHist1.V1
+MyHist1.V2
+MyHist2.V1
+MyHist2.V2
+```
+
+The variant name is allowed to be an empty string, to make it easy to define
+patterns that include legacy histogram names. When defining new histograms,
+prefer an **explicit variant name** instead. Example:
+
+```
+<histogram name="MyHist1.A{MyVariants}">
+  <token key="MyVariants">
+    <variant name="" summary="All"/>
+    <variant name=".B" summary="B"/>
+  </token>
+</histogram>
+```
+
+The complete list of histograms will be:
+
+```
+MyHist1.A
+MyHist1.A.B
+```
+
+## Histogram suffixes (_deprecated in favor of pattern histograms_)
+
+The histogram suffixes syntax will be replaced by the above pattern histograms.
+The new pattern histogram syntax provides a much clearer picture of what
+histograms will be generated and it’s easier to use.
+*   It allows users to put format strings in the middle of histogram name and
+    specify variants that will be used to replace these format strings both
+    inline and out-of-line.
+*   It gives users better control over each generated histogram's description.
+    The placeholder string in the histogram's summary will be replaced by the
+    attribute of the corresponding variant.
 
 Each histogram_suffixes tag lists the histograms that it affects. The complete
 list of histograms is computed by appending (or prepending - see below) the
-suffix names to each of the affected histograms. For example, if we define the following:
+suffix names to each of the affected histograms. For example, if we define the
+following:
 
   ```
   <histogram name="FileLoadLatency"/>
@@ -79,8 +198,8 @@ Optionally, ordering can be specified as "prefix,N" where N indicates after
 how many dots the suffix should be inserted (default=1). The affected-histogram
 name has to have at least N dots in it.
 
-If a `<histogram>` or a `<suffix>` element is only provided so that its name can be
-extended by `<histogram_suffixes>`, the element should be annotated with the
+If a `<histogram>` or a `<suffix>` element is only provided so that its name can
+be extended by `<histogram_suffixes>`, the element should be annotated with the
 attribute `base="true"`. This instructs tools not to treat the base name as a
 distinct histogram.