golang.org/toolchain@v0.0.1-go1.9rc2.windows-amd64/src/cmd/vendor/github.com/google/pprof/doc/pprof.md (about)

     1  # pprof
     2  
     3  pprof is a tool for visualization and analysis of profiling data.
     4  
     5  pprof reads a collection of profiling samples in profile.proto format and
     6  generates reports to visualize and help analyze the data. It can generate both
     7  text and graphical reports (through the use of the dot visualization package).
     8  
     9  profile.proto is a protocol buffer that describes a set of callstacks
    10  and symbolization information. A common usage is to represent a set of
    11  sampled callstacks from statistical profiling. The format is
    12  described on the src/proto/profile.proto file. For details on protocol
    13  buffers, see https://developers.google.com/protocol-buffers
    14  
    15  Profiles can be read from a local file, or over http. Multiple
    16  profiles of the same type can be aggregated or compared.
    17  
    18  If the profile samples contain machine addresses, pprof can symbolize
    19  them through the use of the native binutils tools (addr2line and nm).
    20  
    21  # pprof profiles
    22  
    23  pprof operates on data in the profile.proto format. Each profile is a collection
    24  of samples, where each sample is associated to a point in a location hierarchy,
    25  one or more numeric values, and a set of labels. Often these profiles represents
    26  data collected through statistical sampling of a program, so each sample
    27  describes a program call stack and a number or weight of samples collected at a
    28  location. pprof is agnostic to the profile semantics, so other uses are
    29  possible. The interpretation of the reports generated by pprof depends on the
    30  semantics defined by the source of the profile.
    31  
    32  # General usage
    33  
    34  The objective of pprof is to generate a report for a profile. The report is
    35  generated from a location hierarchy, which is reconstructed from the profile
    36  samples. Each location contains two values: *flat* is the value of the location
    37  itself, while *cum* is the value of the location plus all its
    38  descendants. Samples that include a location multiple times (eg for recursive
    39  functions) are counted only once per location.
    40  
    41  The basic usage of pprof is
    42  
    43      pprof <format> [options] source
    44  
    45  Where *format* selects the nature of the report, and *options* configure the
    46  contents of the report. Each option has a value, which can be boolean, numeric,
    47  or strings. While only one format can be specified, most options can be selected
    48  independently of each other.
    49  
    50  Some common pprof options are:
    51  
    52  * **-flat [default]:** Sort entries based on their flat weight, on text reports.
    53  * **-cum:** Sort entries based on cumulative weight, on text reports.
    54  * **-functions [default]:** Accumulate samples at the function level; profile
    55    locations that describe the same function will be merged into a report entry.
    56  * **-lines:** Accumulate samples at the source line level; profile locations that
    57    describe the same function will be merged into a report entry.
    58  * **-addresses:** Accumulate samples at the instruction address; profile locations
    59    that describe the same function address will be merged into a report entry.
    60  * **-nodecount= _int_:** Maximum number of entries in the report. pprof will only print
    61    this many entries and will use heuristics to select which entries to trim.
    62  * **-focus= _regex_:** Only include samples that include a report entry matching
    63    *regex*.
    64  * **-ignore= _regex_:** Do not include samples that include a report entry matching
    65    *regex*.
    66  * **-show= _regex_:** Only show entries that match *regex*.
    67  * **-hide= _regex_:** Do not show entries that match *regex*.
    68  
    69  Each sample in a profile may include multiple values, representing different
    70  entities associated to the sample. pprof reports include a single sample value,
    71  which by convention is the last one specified in the report. The `sample_index=`
    72  option selects which value to use, and can be set to a number (from 0 to the
    73  number of values - 1) or the name of the sample value.
    74  
    75  Sample values are numeric values associated to a unit. If pprof can recognize
    76  these units, it will attempt to scale the values to a suitable unit for
    77  visualization. The `unite=` option will force the use of a specific unit. For
    78  example, `sample_index=sec` will force any time values to be reported in
    79  seconds. pprof recognizes most common time and memory size units.
    80  
    81  ## Text reports
    82  
    83  pprof text reports show the location hierarchy in text format.
    84  
    85  * **-text:** Prints the location entries, one per line, including the flat and cum
    86    values.
    87  * **-tree:** Prints each location entry with its predecessors and successors.
    88  * **-peek= _regex_:** Print the location entry with all its predecessors and
    89    successors, without trimming any entries.
    90  * **-traces:** Prints each sample with a location per line.
    91  
    92  ## Graphical reports
    93  
    94  pprof can generate graphical reports on the DOT format, and convert them to
    95  multiple formats using the graphviz package.
    96  
    97  These reports represent the location hierarchy as a graph, with a report entry
    98  represented as a node. Solid edges represent a direct connection between
    99  entries, while dotted edges represent a connection where some intermediate nodes
   100  have been removed. Nodes are removed using heuristics to limit the size of
   101  the graph, controlled by the *nodecount* option.
   102  
   103  The size of each node represents the flat weight of the node, and the width of
   104  each edge represents the cumulative weight of all samples going through
   105  it. Nodes are colored according to their cumulative weight, highlighting the
   106  paths with the highest cum weight.
   107  
   108  * **-dot:** Generates a report in .dot format. All other formats are generated from
   109    this one.
   110  * **-svg:** Generates a report in SVG format.
   111  * **-web:** Generates a report in SVG format on a temp file, and starts a web
   112    browser to view it.
   113  * **-png, -jpg, -gif, -pdf:** Generates a report in these formats,
   114  
   115  ## Annotated code
   116  
   117  pprof can also generate reports of annotated source with samples associated to
   118  them. For these, the source or binaries must be locally available, and the
   119  profile must contain data with the appropriate level of detail.
   120  
   121  pprof will look for source files on its current working directory and all its
   122  ancestors. pprof will look for binaries on the directories specified in the
   123  `$PPROF_BINARY_PATH` environment variable, by default `$HOME/pprof/binaries`
   124  (`%USERPROFILE%\pprof\binaries` on Windows). It will look binaries up by name,
   125  and if the profile includes linker build ids, it will also search for them in
   126  a directory named as the build id.
   127  
   128  pprof uses the binutils tools to examine and disassemble the binaries. By
   129  default it will search for those tools in the current path, but it can also
   130  search for them in a directory pointed to by the environment variable
   131  `$PPROF_TOOLS`.
   132  
   133  * **-disasm= _regex_:** Generates an annotated source listing for functions matching
   134    regex, with flat/cum weights for each source line.
   135  * **-list= _regex_:** Generates an annotated disassembly listing for functions
   136    matching *regex*.
   137  * **-weblist= _regex_:** Generates a source/assembly combined annotated listing for
   138    functions matching *regex*, and starts a web browser to display it.
   139  
   140  # Fetching profiles
   141  
   142  pprof can read profiles from a file or directly from a URL over http. Its native
   143  format is a gzipped profile.proto file, but it can also accept some legacy
   144  formats generated by [gperftools](https://github.com/gperftools/gperftools).
   145  
   146  When fetching from a URL handler, pprof accepts options to indicate how much to
   147  wait for the profile.
   148  
   149  * **-seconds= _int_:** Makes pprof request for a profile with the specified duration
   150    in seconds. Only makes sense for profiles based on elapsed time, such as CPU
   151    profiles.
   152  * **-timeout= _int_:** Makes pprof wait for the specified timeout when retrieving a
   153    profile over http. If not specified, pprof will use heuristics to determine a
   154    reasonable timeout.
   155  
   156  If multiple profiles are specified, pprof will fetch them all and merge
   157  them. This is useful to combine profiles from multiple processes of a
   158  distributed job. The profiles may be from different programs but must be
   159  compatible (for example, CPU profiles cannot be combined with heap profiles).
   160  
   161  pprof can subtract a profile from another in order to compare them. For that,
   162  use the **-base= _profile_** option, where *profile* is the filename or URL for the
   163  profile to be subtracted. This may result on some report entries having negative
   164  values.
   165  
   166  ## Symbolization
   167  
   168  pprof can add symbol information to a profile that was collected only with
   169  address information. This is useful for profiles for compiled languages, where
   170  it may not be easy or even possible for the profile source to include function
   171  names or source coordinates.
   172  
   173  pprof can extract the symbol information locally by examining the binaries using
   174  the binutils tools, or it can ask running jobs that provide a symbolization
   175  interface.
   176  
   177  pprof will attempt symbolizing profiles by default, and its `-symbolize` option
   178  provides some control over symbolization:
   179  
   180  * **-symbolize=none:** Disables any symbolization from pprof.
   181  
   182  * **-symbolize=local:** Only attempts symbolizing the profile from local
   183    binaries using the binutils tools.
   184  
   185  * **-symbolize=remote:** Only attempts to symbolize running jobs by contacting
   186    their symbolization handler.
   187  
   188  For local symbolization, pprof will look for the binaries on the paths specified
   189  by the profile, and then it will search for them on the path specified by the
   190  environment variable `$PPROF_BINARY_PATH`. Also, the name of the main binary can
   191  be passed directly to pprof as its first parameter, to override the name or
   192  location of the main binary of the profile, like this:
   193  
   194      pprof /path/to/binary profile.pb.gz
   195  
   196  By default pprof will attempt to demangle and simplify C++ names, to provide
   197  readable names for C++ symbols. It will aggressively discard template and
   198  function parameters. This can be controlled with the `-symbolize=demangle`
   199  option. Note that for remote symbolization mangled names may not be provided by
   200  the symbolization handler.
   201  
   202  * **--symbolize=demangle=none:** Do not perform any demangling. Show mangled
   203    names if available.
   204  
   205  * **-symbolize=demangle=full:** Demangle, but do not perform any
   206    simplification. Show full demangled names if available.
   207  
   208  * **-symbolize=demangle=templates:** Demangle, and trim function parameters, but
   209    not template parameters.
   210