Update pprof documentation on tags. (#722)
Add missing options, restructure the text a bit.
diff --git a/doc/README.md b/doc/README.md
index 8f90e21..12c6dd0 100644
--- a/doc/README.md
+++ b/doc/README.md
@@ -29,7 +29,7 @@
possible. The interpretation of the reports generated by pprof depends on the
semantics defined by the source of the profile.
-# Usage Modes
+# Usage modes
There are few different ways of using `pprof`.
@@ -66,12 +66,12 @@
The objective of pprof is to generate a report for a profile. The report is
generated from a location hierarchy, which is reconstructed from the profile
-samples. Each location contains two values:
+samples. Each location contains two values:
* *flat*: the value of the location itself.
-* *cum*: the value of the location plus all its descendants.
+* *cum*: the value of the location plus all its descendants.
-Samples that include a location multiple times (e.g. for recursive functions)
+Samples that include a location multiple times (e.g. for recursive functions)
are counted only once per location.
## Options
@@ -115,17 +115,23 @@
example, `unit=sec` will force any time values to be reported in
seconds. pprof recognizes most common time and memory size units.
-## Tag filtering
+## Tags
-Samples in a profile may have tags. These tags have a name and a value; this
-value can be either numeric or a string. pprof can select samples from a
-profile based on these tags using the `-tagfocus` and `-tagignore` options.
+Samples in a profile may have tags. These tags have a name and a value. The
+value can be either numeric or a string; the numeric values can be associated
+with a unit. Tags are used as additional dimensions that the sample values can
+be broken by. The most common use of tags is selecting samples from a profile
+based on the tag values. pprof also supports tags at the visualization time.
-Generally, these options work as follows:
-* **-tagfocus=_regex_** or **-tagfocus=_range_:** Restrict to samples with tags
- matched by regexp or in range.
-* **-tagignore=_regex_** or **-tagignore=_range_:** Discard samples with tags
- matched by regexp or in range.
+### Tag filtering
+
+The `-tagfocus` option is the most used option for selecting data in a profile
+based on tag values. It has the syntax of **-tagfocus=_regex_** or
+**-tagfocus=_range_:** which will restrict the data to samples with tags matched
+by regexp or in range. The `-tagignore` option has the identical syntax and can
+be used to filter out the samples that have matching tags. If both `-tagignore`
+and `-tagfocus` are specified and match a given sample, then the sample will be
+discarded.
When using `-tagfocus=regex` and `-tagignore=regex`, the regex will be compared
to each value associated with each tag. If one specifies a value
@@ -139,7 +145,7 @@
a value like `regex1,regex2`, then samples with a tag value (paired with the
specified tag name) matching either `regex1` or matching `regex2` will match.
-Here are examples explaining how `tagfocus` can be used:
+Here are examples explaining how `-tagfocus` can be used:
* `-tagfocus 128kb:512kb` accepts a sample iff it has any numeric tag with
memory value in the specified range.
@@ -155,11 +161,24 @@
* `-tagfocus mytag=myvalue1,myvalue2` matches if either of the two tag values
are present.
-`-tagignore` works similarly, except that it discards matching samples, instead
-of keeping them.
+### Tag visualization
-If both the `-tagignore` and `-tagfocus` expressions (either a regexp or a
-range) match a given sample, then the sample will be discarded.
+To list the tags and their values available in a profile use **-tags** option.
+It will output the available tags and their values as well as the breakdown of
+the sample value by the values of each tag.
+
+The pprof callgraph reports, such as `-web` or raw `-dot`, will automatically
+visualize the values for all tags as pseudo nodes in the graph. Use `-tagshow`
+and `-taghide` options to limit what tags are displayed. The options accept a
+regular expression that is matched against the tag name to show or hide it
+respectively.
+
+Options `-tagroot` and `-tagleaf` can be used to create pseudo stack frames to
+the profile samples. For example, `-tagroot=mytag` will add stack frames at the
+root of the profile call tree with the value of the tag for the corresponding
+samples. Similarly, `-tagleaf=mytag` will add such stack frames as leaf nodes of
+each sample. These options are useful when visualizing a profile in tree formats
+such as the tree view in the `-http` mode web UI.
## Text reports
@@ -199,7 +218,7 @@
* **Node Font Size**:
* larger font size means larger absolute flat values.
- * smaller font size means smaller absolute flat values.
+ * smaller font size means smaller absolute flat values.
* **Edge Weight**:
* thicker edges indicate more resources were used along that path.
@@ -224,26 +243,26 @@
* For nodes:
* `(*Rand).Read` has a small flat value and a small cum value because the
the font is small and the node is grey.
- * `(*compressor).deflate` has a large flat value and a large cum value because the font
+ * `(*compressor).deflate` has a large flat value and a large cum value because the font
is large and the node is red.
* `(*Writer).Flush` has a small flat value and a large cum value because the font is
small and the node is red.
* For edges:
- * the edge between `(*Writer).Write` and `(*compressor).write`:
+ * the edge between `(*Writer).Write` and `(*compressor).write`:
* Since it is a dashed edge, some nodes were removed between those two.
* Since it is thick and red, more resources were used in call stacks between
those two nodes.
* the edge between `(*Rand).Read` and `read`:
* Since it is a dashed edge, some nodes were removed between those two.
- * Since it is thin and grey, fewer resources were used in call stacks
+ * Since it is thin and grey, fewer resources were used in call stacks
between those two nodes.
* the edge between `read` and `(*rngSource).Int63`:
* Since it is a solid edge, there are no nodes between those two (i.e. it
was a direct call).
* Since it is thin and grey, fewer resources were used in call stacks
between those two nodes.
-
+
## Annotated code
pprof can also generate reports of annotated source with samples associated to
@@ -286,7 +305,7 @@
the output are relative to the difference between the total for the source
profile and the total for the base profile.
-The **-normalize** flag can be used when a base profile is specified with either
+The **-normalize** flag can be used when a base profile is specified with either
the `-diff_base` or the `-base` option. This flag scales the source profile so
that the total of samples in the source profile is equal to the total of samples
in the base profile prior to subtracting the base profile from the source
@@ -303,7 +322,7 @@
When using the **-base** option to subtract one cumulative profile from another
collected on the same program at a later time, percentages will be relative to
the difference between the total for the source profile and the total for
-the base profile, and all values will be positive. In the general case, some
+the base profile, and all values will be positive. In the general case, some
report entries may have negative values and percentages will be relative to the
total of the absolute value of all samples when aggregated at the address level.
@@ -311,7 +330,7 @@
pprof can read profiles from a file or directly from a URL over http or https.
Its native format is a gzipped profile.proto file, but it can
-also accept some legacy formats generated by
+also accept some legacy formats generated by
[gperftools](https://github.com/gperftools/gperftools).
When fetching from a URL handler, pprof accepts options to indicate how much to
@@ -337,7 +356,7 @@
used when fetching and symbolizing profiles.
pprof also supports skipping verification of the server's certificate chain and
-host name when collecting or symbolizing a profile. To skip this verification,
+host name when collecting or symbolizing a profile. To skip this verification,
use "https+insecure" in place of "https" in the URL.
If multiple profiles are specified, pprof will fetch them all and merge
