Master Go’s pprof: Unlock Every Command for Deep Performance Insights

Introduction

Go's pprof tool is a powerful performance analysis utility that helps developers diagnose and optimise program performance. This article provides a detailed walkthrough of pprof’s command‑line options, enabling you to fully exploit its capabilities to improve Go applications.

pprof Tool Overview

pprof analyses Go program performance data, supports multiple output formats and visualisation tools. By using command‑line flags you can control the output format and content flexibly. The following sections describe each command and its purpose.

Command Details

callgrind

callgrind

generates a callgrind‑format graph, which can be visualised with KCachegrind.

Example:

(pprof) callgrind
Generating report in profile001.callgraph.out

comments

comments

prints all profile comment metadata, helping developers understand the profiling context.

Example:

(pprof) comments

disasm

disasm

outputs a list of assembly instructions with sampling annotations, useful for low‑level performance inspection.

Example:

(pprof) disasm net/http.parsePattern
Total: 1MB
ROUTINE ======================== net/http.parsePattern
  512.05kB   512.05kB (flat, cum) 50.00% of Total
         .          .     625ba0: LEAQ 0xfffffeb0(SP), R12                ;pattern.go:84
         .          .     625ba8: CMPQ R12, 0x10(R14)
         .          .     625bac: JBE 0x626b66
         .          .     625bb2: PUSHQ BP
         .          .     625bb3: MOVQ SP, BP
         .          .     625bb6: SUBQ $0x1c8, SP
         .          .     625bbd: MOVQ AX, 0x1d8(SP)
         .          .     625bc5: MOVQ X15, 0x1c0(SP)
         .          .     625bcf: MOVB $0x0, 0x47(SP)
         .          .     625bd4: MOVQ $0x0, 0x88(SP)
         .          .     625be0: MOVUPS X15, 0xb8(SP)
         .          .     625be9: TESTQ BX, BX                            ;pattern.go:85
         .          .     625bec: JE 0x626143
         .          .     625bf2: MOVQ BX, 0x1e0(SP)
         .          .     625bfa: MOVQ AX, 0x1d8(SP)
         .          .     625c02: MOVQ $0x0, 0x60(SP)                     ;pattern.go:88
         .          .     625c0b: MOVUPS X15, 0x190(SP)                   ;pattern.go:89
         .          .     625c14: MOVQ $0x0, 0x1a0(SP)
         .          .     625c20: LEAQ net/http.parsePattern.func1(SB), DX
         .          .     625c27: MOVQ DX, 0x190(SP)
         .          .     625c2f: LEAQ 0xb8(SP), DX
         .          .     625c37: MOVQ DX, 0x198(SP)

dot

dot

generates a DOT‑format graph, which can be processed by Graphviz for complex visualisations.

Example:

(pprof) dot net/http.parsePattern
 digraph "app.exe" {
node [style=filled fillcolor="#f8f8f8"]
subgraph cluster_L { "File: app.exe" [shape=box fontsize=16 label="File: app.exe\lBuild ID: C:\src\uml\2024\05\18\app.exe2024-05-18 20:48:58.1691483 +0800 +08\lType: inuse_space\lTime: May 18, 2024 at 9:23pm (+08)\lActive filters:\l   focus=net/http.parsePattern\lShowing nodes accounting for 512.05kB, 50.00% of 1024.09kB total\l\lSee https://git.io/JfYMW for how to read the graph\l" tooltip="app.exe"] }
N1 [label="http
parsePattern
512.05kB (50.00%)" id="node1" fontsize=24 shape=box tooltip="net/http.parsePattern (512.05kB)" color="#b22100" fillcolor="#edd9d5"]
... (graph omitted for brevity)
}

eog

eog

opens the generated graph with the Eye of GNOME viewer.

Example:

(pprof) eog
exec: "eog": executable file not found in %PATH%

evince

evince

opens the graph with the Evince document viewer, similar to eog.

Example:

(pprof) evince
exec: "evince": executable file not found in %PATH%

gif

gif

creates an animated GIF of the graph, convenient for embedding in web pages or reports.

Example:

(pprof) gif
Generating report in profile001.gif
(pprof) gif net/http.parsePattern
Generating report in profile002.gif

gv

gv

visualises the graph using the X11‑based PostScript/PDF viewer.

Example:

(pprof) gv
exec: "gv": executable file not found in %PATH%

kcachegrind

kcachegrind

opens the callgrind file in KCachegrind for detailed visual analysis.

Example:

(pprof) kcachegrind
exec: "kcachegrind": executable file not found in %PATH%

list

list

prints the source code of functions matching a regular expression, together with profiling annotations.

Example:

(pprof) list net/http.parsePattern
Total: 1MB
ROUTINE ======================== net/http.parsePattern in C:\Program Files\Go\src
et\http\pattern.go
  512.05kB   512.05kB (flat, cum) 50.00% of Total
         .          .     84:func parsePattern(s string) (_ *pattern, err error) {
         .          .     85:   if len(s) == 0 {
         .          .     86:       return nil, errors.New("empty pattern")
         .          .     87:   }
         .          .     88:   off := 0 // offset into string
         .          .     89:   defer func() {
         .          .     90:       if err != nil {
         .          .     91:         err = fmt.Errorf("at offset %d: %w", off, err)
         .          .     92:       }
         .          .     93:   }()
         .          .     94:
         .          .     95:   method, rest, found := strings.Cut(s, " ")
         .          .     96:   if !found {
         .          .     97:       rest = method
         .          .     98:       method = ""
         .          .     99:   }
         .          .    100:   if method != "" && !validMethod(method) {
        101:       return nil, fmt.Errorf("invalid method %q", method)
        102:   }
        ... (rest of source omitted for brevity)

pdf

pdf

generates a PDF version of the graph, suitable for printing and sharing.

Example:

(pprof) pdf net/http.parsePattern
Generating report in profile001.pdf

proto

proto

outputs the profile data in compressed protobuf format, useful for data exchange and storage.

Example:

(pprof) proto net/http.parsePattern
Generating report in profile001.pb.gz

ps

ps

creates a PostScript graph for high‑quality printing.

Example:

(pprof) ps net/http.parsePattern
Generating report in profile001.ps

raw

raw

prints the raw textual representation of the profile, allowing deep custom analysis.

Example:

(pprof) raw net/http.parsePattern
PeriodType: space bytes
Period: 524288
Time: 2024-05-18 21:23:27.8127791 +0800 +08
Samples:
alloc_objects/count alloc_space/bytes inuse_objects/count inuse_space/bytes
       5461     524336       5461     524336: 23 24 25 26 27 28
                bytes:[96]
Locations
     1: 0x860205 M=1 net/textproto.readMIMEHeader C:/Program Files/Go/src/net/textproto/reader.go:571 s=487
     2: 0x8a948d M=1 net/textproto.(*Reader).ReadMIMEHeader C:/Program Files/Go/src/net/textproto/reader.go:482 s=481
         net/http.readRequest C:/Program Files/Go/src/net/http/request.go:1105 s=1051
     3: 0x8b0927 M=1 net/http.(*conn).readRequest C:/Program Files/Go/src/net/http/server.go:1004 s=975
     ... (additional locations omitted for brevity)

tags

tags

lists all tags present in the profile, helping you filter and understand the data dimensions.

Example:

(pprof) tags
 bytes: Total 1.0MB
        1.0MB (  100%): 96B
         0.0B (    0%): 128kB
         0.0B (    0%): 136kB
         0.0B (    0%): 352B
         0.0B (    0%): 648kB
         0.0B (    0%): 80B

text

text

outputs the main performance entries in plain text for quick inspection.

Example:

(pprof) text
Showing nodes accounting for 1024.09kB, 100% of 1024.09kB total
Showing top 10 nodes out of 13
      flat  flat%   sum%        cum   cum%
  512.05kB 50.00% 50.00%   512.05kB 50.00%  net/http.parsePattern
  512.05kB 50.00% 100%   512.05kB 50.00%  sync.runtime_notifyListWait
         0     0% 100%   512.05kB 50.00%  net/http.(*ServeMux).register (inline)
         ... (remaining rows omitted)

top

top

provides a Linux‑like top view of the most expensive functions.

Example:

(pprof) top
Showing nodes accounting for 1024.09kB, 100% of 1024.09kB total
Showing top 10 nodes out of 13
      flat  flat%   sum%        cum   cum%
  512.05kB 50.00% 50.00%   512.05kB 50.00%  net/http.parsePattern
  512.05kB 50.00% 100%   512.05kB 50.00%  sync.runtime_notifyListWait
         ... (remaining rows omitted)

topproto

topproto

combines top and proto, outputting the top entries in compressed protobuf format.

Example:

(pprof) topproto
Generating report in profile002.pb.gz

traces

traces

prints all sampled profile data as text, suitable for detailed per‑sample analysis.

Example:

(pprof) traces net/http.parsePattern
File: app.exe
Build ID: C:\src\uml\2024\05\18\app.exe2024-05-18 20:48:58.1691483 +0800 +08
Type: inuse_space
Time: May 18, 2024 at 9:23pm (+08)
-----------+-------------------------------------------------------
     bytes:  96B
  512.05kB   net/http.parsePattern
             net/http.(*ServeMux).registerErr
             net/http.(*ServeMux).register (inline)
             net/http.HandleFunc
             net/http/pprof.init.0
             runtime.doInit1
             runtime.doInit (inline)
             runtime.main
-----------+-------------------------------------------------------

tree

tree

displays the call graph as an indented text tree, making call relationships easy to read.

Example:

(pprof) tree net/http.parsePattern
Active filters:
   focus=net/http.parsePattern
Showing nodes accounting for 512.05kB, 50.00% of 1024.09kB total
----------------------------------------------------------+-------------
      flat  flat%   sum%        cum   cum%   calls calls% + context
----------------------------------------------------------+-------------
                                          512.05kB   100% |   net/http.(*ServeMux).registerErr
  512.05kB 50.00% 50.00%   512.05kB 50.00%                | net/http.parsePattern
----------------------------------------------------------+-------------
                                          512.05kB   100% |   net/http.HandleFunc (inline)
         0     0% 50.00%   512.05kB 50.00%                | net/http.(*ServeMux).register
... (rest omitted)

web

web

launches the default web browser to visualise the graph, facilitating sharing and presentation.

Example:

(pprof) web

weblist

weblist

shows annotated source code in a web browser, similar to list but with a richer UI.

Example:

(pprof) weblist

Conclusion

By leveraging the rich set of pprof commands, Go developers can comprehensively analyse and optimise program performance. This article has detailed each command and its use case, empowering you to pinpoint bottlenecks, devise effective optimisation strategies, and deliver higher‑quality Go applications.