Repository files navigation

pprof is a tool for visualization and analysis of profiling data.

pprof reads a collection of profiling samples in profile.proto format andgenerates reports to visualize and help analyze the data. It can generate bothtext and graphical reports (through the use of the dot visualization package).

profile.proto is a protocol buffer that describes a set of callstacksand symbolization information. A common usage is to represent a set ofsampled callstacks from statistical profiling. The format isdescribed on theproto/profile.proto file. For details on protocolbuffers, seehttps://developers.google.com/protocol-buffers

Profiles can be read from a local file, or over http. Multipleprofiles of the same type can be aggregated or compared.

If the profile samples contain machine addresses, pprof can symbolizethem through the use of the native binutils tools (addr2line and nm).

This is not an official Google product.

Prerequisites:

• Go development kit of asupported version.Followthese instructions to preparethe environment.

• Graphviz:http://www.graphviz.org/Optional, used to generate graphic visualizations of profiles

To build and install it:

go install github.com/google/pprof@latest

The binary will be installed$GOPATH/bin ($HOME/go/bin by default).

pprof can read a profile from a file or directly from a server via http.Specify the profile input(s) in the command line, and use options toindicate how to format the report.

% pprof -top [main_binary] profile.pb.gzWhere    main_binary:  Local path to the main program binary, to enable symbolization    profile.pb.gz: Local path to the profile in a compressed protobuf, or                   URL to the http service that serves a profile.

pprof -web [main_binary] profile.pb.gz

If no output formatting option is specified, pprof runs on interactive mode,where reads the profile and accepts interactive commands for visualization andrefinement of the profile.

pprof [main_binary] profile.pb.gzThis will open a simple shell that takes pprof commands to generate reports.Type 'help' for available commands/options.

If the-http flag is specified, pprof starts a web server atthe specified host:port that provides an interactive web-based interface to pprof.Host is optional, and is "localhost" by default. Port is optional, and is arandom available port by default.-http=":" starts a server locally ata random port.

pprof -http=[host]:[port] [main_binary] profile.pb.gz

The preceding command should automatically open your web browser atthe right page; if not, you can manually visit the specified port inyour web browser.

pprof can readperf.data files generated by theLinux perf tool by using theperf_to_profile program from theperf_data_converter package.

To view disassembly of profiles collected from Go programs compiled as Windows executables,the executable must be built withgo build -buildmode=exe. LLVM or GCC must be installed,so required tools likeaddr2line andnm are available topprof.

Seedoc/README.md for more detailed end-user documentation.

SeeCONTRIBUTING.md for contribution documentation.

Seeproto/README.md for a description of the profile.proto format.