Introduction

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

Add probe_gran to continue collect process memory status.

pprofplus 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, pprofplus can symbolize them through the use of the native binutils tools (addr2line and nm).

This is not an official Google product.

Building pprofplus

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/shippomx/pprofplusplus

Remember to set GOPATH to the directory where you want pprofplus to be installed. The binary will be in $GOPATH/bin and the sources under $GOPATH/src/github.com/shippomx/pprofplusplus.

Basic usage

pprofplus 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.

Capture process running memory time granularity

% pprofplus -probe_gran=10s
# 1m 10min, etc.

Generate a text report of the profile, sorted by hotness:

% pprofplus -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:

pprofplus -web [main_binary] profile.pb.gz

Run pprofplus on interactive mode:

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

pprofplus [main_binary] profile.pb.gz

This will open a simple shell that takes pprofplus commands to generate reports.
Type 'help' for available commands/options.

Run pprofplus via a web interface

If the -http flag is specified, pprofplus starts a web server at the specified host:port that provides an interactive web-based interface to pprofplus. 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.

pprofplus -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 pprofplus with Linux Perf

pprofplus 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 pprofplus.

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.