From f486417078936b7bb3f8a4678003e56de9f89b9b Mon Sep 17 00:00:00 2001 From: Maggie Nolan Date: Tue, 8 May 2018 13:47:06 -0700 Subject: [PATCH] update documents --- doc/README.md | 70 +++++++++++++++++++++++++-------------------------- 1 file changed, 34 insertions(+), 36 deletions(-) diff --git a/doc/README.md b/doc/README.md index 1fa8dffe..c76ef5d5 100644 --- a/doc/README.md +++ b/doc/README.md @@ -216,53 +216,30 @@ search for them in a directory pointed to by the environment variable * **-weblist= _regex_:** Generates a source/assembly combined annotated listing for functions matching *regex*, and starts a web browser to display it. -# Fetching profiles - -pprof can read profiles from a file or directly from a URL over http. Its native -format is a gzipped profile.proto file, but it can 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 -wait for the profile. - -* **-seconds= _int_:** Makes pprof request for a profile with the specified duration - in seconds. Only makes sense for profiles based on elapsed time, such as CPU - profiles. -* **-timeout= _int_:** Makes pprof wait for the specified timeout when retrieving a - profile over http. If not specified, pprof will use heuristics to determine a - reasonable timeout. - -If multiple profiles are specified, pprof will fetch them all and merge -them. This is useful to combine profiles from multiple processes of a -distributed job. The profiles may be from different programs but must be -compatible (for example, CPU profiles cannot be combined with heap profiles). - - ## Comparing profiles pprof can subtract one profile from another, provided the profiles are of -compatible types. pprof has two options which can be used to specify the -filename or URL for a profile to be subtracted from the source profile: +compatible types (i.e. two heap profiles). pprof has two options which can be +used to specify the filename or URL for a profile to be subtracted from the +source profile: -* **-diff_base= _profile_:** useful for comparing any two profiles of compatible -types (i.e. any two heap profiles). Percentages in the output are relative to -the total of samples in the diff base profile. +* **-diff_base= _profile_:** useful for comparing two profiles. Percentages in +the output are relative to the total of samples in the diff base profile. * **-base= _profile_:** useful for subtracting a cumulative profile, like a [golang block profile](https://golang.org/doc/diagnostics.html#profiling), from another cumulative profile collected from the same program at a later time. When comparing cumulative profiles collected on the same profile, percentages in -the output are relative to the the difference between the total for the source +the output are relative to the difference between the total for the source profile and the total for the base profile. -The following flag can be used when a base profile is specified with either the -`-diff_base` or the `-base` option: - -* **-normalize**: Scales the source profile so that 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 profile. Useful for determining -the relative differences between profiles, for example, which profile has a -larger percentage of CPU time used in a particular function. +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 +profile. Useful for determining the relative differences between profiles, for +example, which profile has a larger percentage of CPU time used in a particular +function. When using the **-diff_base** option, some report entries may have negative values. If the merged profile is output as a protocol buffer, all samples in the @@ -277,6 +254,27 @@ 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. +# Fetching profiles + +pprof can read profiles from a file or directly from a URL over http. Its native +format is a gzipped profile.proto file, but it can 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 +wait for the profile. + +* **-seconds= _int_:** Makes pprof request for a profile with the specified duration + in seconds. Only makes sense for profiles based on elapsed time, such as CPU + profiles. +* **-timeout= _int_:** Makes pprof wait for the specified timeout when retrieving a + profile over http. If not specified, pprof will use heuristics to determine a + reasonable timeout. + +If multiple profiles are specified, pprof will fetch them all and merge +them. This is useful to combine profiles from multiple processes of a +distributed job. The profiles may be from different programs but must be +compatible (for example, CPU profiles cannot be combined with heap profiles). + ## Symbolization pprof can add symbol information to a profile that was collected only with