1[](https://github.com/google/pprof/actions)
2[](https://codecov.io/gh/google/pprof)
3[](https://pkg.go.dev/github.com/google/pprof/profile)
4
5# Introduction
6
7pprof is a tool for visualization and analysis of profiling data.
8
9pprof reads a collection of profiling samples in profile.proto format and
10generates reports to visualize and help analyze the data. It can generate both
11text and graphical reports (through the use of the dot visualization package).
12
13profile.proto is a protocol buffer that describes a set of callstacks
14and symbolization information. A common usage is to represent a set of
15sampled callstacks from statistical profiling. The format is
16described on the [proto/profile.proto](./proto/profile.proto) file. For details on protocol
17buffers, see https://developers.google.com/protocol-buffers
18
19Profiles can be read from a local file, or over http. Multiple
20profiles of the same type can be aggregated or compared.
21
22If the profile samples contain machine addresses, pprof can symbolize
23them through the use of the native binutils tools (addr2line and nm).
24
25**This is not an official Google product.**
26
27# Building pprof
28
29Prerequisites:
30
31- Go development kit of a [supported version](https://golang.org/doc/devel/release.html#policy).
32 Follow [these instructions](http://golang.org/doc/code.html) to prepare
33 the environment.
34
35- Graphviz: http://www.graphviz.org/
36 Optional, used to generate graphic visualizations of profiles
37
38To build and install it:
39
40 go install github.com/google/pprof@latest
41
42The binary will be installed `$GOPATH/bin` (`$HOME/go/bin` by default).
43
44# Basic usage
45
46pprof can read a profile from a file or directly from a server via http.
47Specify the profile input(s) in the command line, and use options to
48indicate how to format the report.
49
50## Generate a text report of the profile, sorted by hotness:
51
52```
53% pprof -top [main_binary] profile.pb.gz
54Where
55 main_binary: Local path to the main program binary, to enable symbolization
56 profile.pb.gz: Local path to the profile in a compressed protobuf, or
57 URL to the http service that serves a profile.
58```
59
60## Generate a graph in an SVG file, and open it with a web browser:
61
62```
63pprof -web [main_binary] profile.pb.gz
64```
65
66## Run pprof on interactive mode:
67
68If no output formatting option is specified, pprof runs on interactive mode,
69where reads the profile and accepts interactive commands for visualization and
70refinement of the profile.
71
72```
73pprof [main_binary] profile.pb.gz
74
75This will open a simple shell that takes pprof commands to generate reports.
76Type 'help' for available commands/options.
77```
78
79## Run pprof via a web interface
80
81If the `-http` flag is specified, pprof starts a web server at
82the specified host:port that provides an interactive web-based interface to pprof.
83Host is optional, and is "localhost" by default. Port is optional, and is a
84random available port by default. `-http=":"` starts a server locally at
85a random port.
86
87```
88pprof -http=[host]:[port] [main_binary] profile.pb.gz
89```
90
91The preceding command should automatically open your web browser at
92the right page; if not, you can manually visit the specified port in
93your web browser.
94
95## Using pprof with Linux Perf
96
97pprof can read `perf.data` files generated by the
98[Linux perf](https://perf.wiki.kernel.org/index.php/Main_Page) tool by using the
99`perf_to_profile` program from the
100[perf_data_converter](https://github.com/google/perf_data_converter) package.
101
102## Viewing disassembly on Windows
103
104To view disassembly of profiles collected from Go programs compiled as Windows executables,
105the executable must be built with `go build -buildmode=exe`. LLVM or GCC must be installed,
106so required tools like `addr2line` and `nm` are available to `pprof`.
107
108## Further documentation
109
110See [doc/README.md](doc/README.md) for more detailed end-user documentation.
111
112See [CONTRIBUTING.md](CONTRIBUTING.md) for contribution documentation.
113
114See [proto/README.md](proto/README.md) for a description of the profile.proto format.
View as plain text