README
Introduction
pprof is a tool for visualization and analysis of profiling data.
pprof reads a collection of profiling samples in profile.proto format and generates reports to visualize and help analyze the data. It can generate both text and graphical reports (through the use of the dot visualization package).
profile.proto is a protocol buffer that describes a set of callstacks and symbolization information. A common usage is to represent a set of sampled callstacks from statistical profiling. The format is described on the proto/profile.proto file. For details on protocol buffers, see https://developers.google.com/protocol-buffers
Profiles can be read from a local file, or over http. Multiple profiles of the same type can be aggregated or compared.
If the profile samples contain machine addresses, pprof can symbolize them through the use of the native binutils tools (addr2line and nm).
This is not an official Google product.
Building pprof
Prerequisites:
-
Go development kit of a supported version. Follow these instructions to install the go tool and set up GOPATH.
-
Graphviz: http://www.graphviz.org/ Optional, used to generate graphic visualizations of profiles
To build and install it, use the go get
tool.
go get -u github.com/google/pprof
Remember to set GOPATH to the directory where you want pprof to be
installed. The binary will be in $GOPATH/bin
and the sources under
$GOPATH/src/github.com/google/pprof
.
Basic usage
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 to indicate how to format the report.
Generate a text report of the profile, sorted by hotness:
% pprof -top [main_binary] profile.pb.gz
Where
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.
Generate a graph in an SVG file, and open it with a web browser:
pprof -web [main_binary] profile.pb.gz
Run pprof on interactive mode:
If no output formatting option is specified, pprof runs on interactive mode, where reads the profile and accepts interactive commands for visualization and refinement of the profile.
pprof [main_binary] profile.pb.gz
This will open a simple shell that takes pprof commands to generate reports.
Type 'help' for available commands/options.
Run pprof via a web interface
If the -http
flag is specified, pprof starts a web server at
the 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 a
random available port by default. -http=":"
starts a server locally at
a random port.
pprof -http=[host]:[port] [main_binary] profile.pb.gz
The preceding command should automatically open your web browser at the right page; if not, you can manually visit the specified port in your web browser.
Using pprof with Linux Perf
pprof can read perf.data
files generated by the
Linux perf tool by using the
perf_to_profile
program from the
perf_data_converter package.
Viewing disassembly on Windows
To view disassembly of profiles collected from Go programs compiled as Windows executables,
the executable must be built with go build -buildmode=exe
. LLVM or GCC must be installed,
so required tools like addr2line
and nm
are available to pprof
.
Further documentation
See doc/README.md for more detailed end-user documentation.
See CONTRIBUTING.md for contribution documentation.
See proto/README.md for a description of the profile.proto format.
Documentation
Overview ¶
pprof is a tool for collection, manipulation and visualization of performance profiles.
Directories
Path | Synopsis |
---|---|
Package driver provides an external entry point to the pprof driver.
|
Package driver provides an external entry point to the pprof driver. |
Package pprof is used in conjunction with github.com/dvyukov/go-fuzz/go-fuzz to fuzz ParseData function.
|
Package pprof is used in conjunction with github.com/dvyukov/go-fuzz/go-fuzz to fuzz ParseData function. |
Package profile provides a representation of profile.proto and methods to encode/decode profiles in this format.
|
Package profile provides a representation of profile.proto and methods to encode/decode profiles in this format. |
third_party
|
|
internal
|
|
binutils
Package binutils provides access to the GNU binutils.
|
Package binutils provides access to the GNU binutils. |
driver
Package driver implements the core pprof functionality.
|
Package driver implements the core pprof functionality. |
elfexec
Package elfexec provides utility routines to examine ELF binaries.
|
Package elfexec provides utility routines to examine ELF binaries. |
graph
Package graph collects a set of samples into a directed graph.
|
Package graph collects a set of samples into a directed graph. |
measurement
Package measurement export utility functions to manipulate/format performance profile sample values.
|
Package measurement export utility functions to manipulate/format performance profile sample values. |
plugin
Package plugin defines the plugin implementations that the main pprof driver requires.
|
Package plugin defines the plugin implementations that the main pprof driver requires. |
proftest
Package proftest provides some utility routines to test other packages related to profiles.
|
Package proftest provides some utility routines to test other packages related to profiles. |
report
Package report summarizes a performance profile into a human-readable report.
|
Package report summarizes a performance profile into a human-readable report. |
symbolizer
Package symbolizer provides a routine to populate a profile with symbol, file and line number information.
|
Package symbolizer provides a routine to populate a profile with symbol, file and line number information. |
symbolz
Package symbolz symbolizes a profile using the output from the symbolz service.
|
Package symbolz symbolizes a profile using the output from the symbolz service. |
transport
Package transport provides a mechanism to send requests with https cert, key, and CA.
|
Package transport provides a mechanism to send requests with https cert, key, and CA. |