version: 1.10

package pprof

import "runtime/pprof"

Overview

Package pprof writes runtime profiling data in the format expected by the pprof
visualization tool.

Profiling a Go program

The first step to profiling a Go program is to enable profiling. Support for
profiling benchmarks built with the standard testing package is built into go
test. For example, the following command runs benchmarks in the current
directory and writes the CPU and memory profiles to cpu.prof and mem.prof:

  1. go test -cpuprofile cpu.prof -memprofile mem.prof -bench .

To add equivalent profiling support to a standalone program, add code like the
following to your main function:

  1. var cpuprofile = flag.String("cpuprofile", "", "write cpu profile to `file`")
  2. var memprofile = flag.String("memprofile", "", "write memory profile to `file`")
  4. func main() {
  5.     flag.Parse()
  6.     if *cpuprofile != "" {
  7.         f, err := os.Create(*cpuprofile)
  8.         if err != nil {
  9.             log.Fatal("could not create CPU profile: ", err)
  10.         }
  11.         if err := pprof.StartCPUProfile(f); err != nil {
  12.             log.Fatal("could not start CPU profile: ", err)
  13.         }
  14.         defer pprof.StopCPUProfile()
  15.     }
  17.     // ... rest of the program ...
  19.     if *memprofile != "" {
  20.         f, err := os.Create(*memprofile)
  21.         if err != nil {
  22.             log.Fatal("could not create memory profile: ", err)
  23.         }
  24.         runtime.GC() // get up-to-date statistics
  25.         if err := pprof.WriteHeapProfile(f); err != nil {
  26.             log.Fatal("could not write memory profile: ", err)
  27.         }
  28.         f.Close()
  29.     }
  30. }

There is also a standard HTTP interface to profiling data. Adding the following
line will install handlers under the /debug/pprof/ URL to download live
profiles:

  1. import _ "net/http/pprof"

See the net/http/pprof package for more details.

Profiles can then be visualized with the pprof tool:

  1. go tool pprof cpu.prof

There are many commands available from the pprof command line. Commonly used
commands include “top”, which prints a summary of the top program hot-spots, and
“web”, which opens an interactive graph of hot-spots and their call graphs. Use
“help” for information on all pprof commands.

For more information about pprof, see
https://github.com/google/pprof/blob/master/doc/pprof.md.

Index

Package files

elf.go label.go map.go pprof.go proto.go protobuf.go protomem.go runtime.go

func Do


  1. func Do(ctx context.Context, labels LabelSet, f func(context.Context))


Do calls f with a copy of the parent context with the given labels added to the
parent’s label map. Each key/value pair in labels is inserted into the label map
in the order provided, overriding any previous value for the same key. The
augmented label map will be set for the duration of the call to f and restored
once f returns.

func ForLabels


  1. func ForLabels(ctx context.Context, f func(key, value string) bool)


ForLabels invokes f with each label set on the context. The function f should
return true to continue iteration or false to stop iteration early.

func Label


  1. func Label(ctx context.Context, key string) (string, bool)


Label returns the value of the label with the given key on ctx, and a boolean
indicating whether that label exists.

func Profiles


  1. func Profiles() []Profile


Profiles returns a slice of all the known profiles, sorted by name.

func SetGoroutineLabels


  1. func SetGoroutineLabels(ctx context.Context)


SetGoroutineLabels sets the current goroutine’s labels to match ctx. This is a
lower-level API than Do, which should be used instead when possible.

func StartCPUProfile


  1. func StartCPUProfile(w io.Writer) error


StartCPUProfile enables CPU profiling for the current process. While profiling,
the profile will be buffered and written to w. StartCPUProfile returns an error
if profiling is already enabled.

On Unix-like systems, StartCPUProfile does not work by default for Go code built
with -buildmode=c-archive or -buildmode=c-shared. StartCPUProfile relies on the
SIGPROF signal, but that signal will be delivered to the main program’s SIGPROF
signal handler (if any) not to the one used by Go. To make it work, call
os/signal.Notify for syscall.SIGPROF, but note that doing so may break any
profiling being done by the main program.

func StopCPUProfile


  1. func StopCPUProfile()


StopCPUProfile stops the current CPU profile, if any. StopCPUProfile only
returns after all the writes for the profile have completed.

func WithLabels


  1. func WithLabels(ctx context.Context, labels LabelSet) context.Context


WithLabels returns a new context.Context with the given labels added. A label
overwrites a prior label with the same key.

func WriteHeapProfile


  1. func WriteHeapProfile(w io.Writer) error


WriteHeapProfile is shorthand for Lookup(“heap”).WriteTo(w, 0). It is preserved
for backwards compatibility.

type LabelSet


  1. type LabelSet struct {
        // contains filtered or unexported fields
    }


LabelSet is a set of labels.

func Labels


  1. func Labels(args …string) LabelSet


Labels takes an even number of strings representing key-value pairs and makes a
LabelSet containing them. A label overwrites a prior label with the same key.

type Profile


  1. type Profile struct {
        // contains filtered or unexported fields
    }


A Profile is a collection of stack traces showing the call sequences that led to
instances of a particular event, such as allocation. Packages can create and
maintain their own profiles; the most common use is for tracking resources that
must be explicitly closed, such as files or network connections.

A Profile’s methods can be called from multiple goroutines simultaneously.

Each Profile has a unique name. A few profiles are predefined:

goroutine - stack traces of all current goroutines
heap - a sampling of all heap allocations
threadcreate - stack traces that led to the creation of new OS threads
block - stack traces that led to blocking on synchronization primitives
mutex - stack traces of holders of contended mutexes

These predefined profiles maintain themselves and panic on an explicit Add or
Remove method call.

The heap profile reports statistics as of the most recently completed garbage
collection; it elides more recent allocation to avoid skewing the profile away
from live data and toward garbage. If there has been no garbage collection at
all, the heap profile reports all known allocations. This exception helps mainly
in programs running without garbage collection enabled, usually for debugging
purposes.

The CPU profile is not available as a Profile. It has a special API, the
StartCPUProfile and StopCPUProfile functions, because it streams output to a
writer during profiling.

func Lookup


  1. func Lookup(name string) Profile


Lookup returns the profile with the given name, or nil if no such profile
exists.

func NewProfile


  1. func NewProfile(name string) Profile


NewProfile creates a new profile with the given name. If a profile with that
name already exists, NewProfile panics. The convention is to use a
‘import/path.’ prefix to create separate name spaces for each package. For
compatibility with various tools that read pprof data, profile names should not
contain spaces.

func (Profile) Add


  1. func (p Profile) Add(value interface{}, skip int)


Add adds the current execution stack to the profile, associated with value. Add
stores value in an internal map, so value must be suitable for use as a map key
and will not be garbage collected until the corresponding call to Remove. Add
panics if the profile already contains a stack for value.

The skip parameter has the same meaning as runtime.Caller’s skip and controls
where the stack trace begins. Passing skip=0 begins the trace in the function
calling Add. For example, given this execution stack:

Add
called from rpc.NewClient
called from mypkg.Run
called from main.main

Passing skip=0 begins the stack trace at the call to Add inside rpc.NewClient.
Passing skip=1 begins the stack trace at the call to NewClient inside mypkg.Run.

func (Profile) Count


  1. func (p Profile) Count() int


Count returns the number of execution stacks currently in the profile.

func (Profile) Name


  1. func (p Profile) Name() string


Name returns this profile’s name, which can be passed to Lookup to reobtain the
profile.

func (Profile) Remove


  1. func (p Profile) Remove(value interface{})


Remove removes the execution stack associated with value from the profile. It is
a no-op if the value is not in the profile.

func (Profile) WriteTo


  1. func (p *Profile) WriteTo(w io.Writer, debug int) error


WriteTo writes a pprof-formatted snapshot of the profile to w. If a write to w
returns an error, WriteTo returns that error. Otherwise, WriteTo returns nil.

The debug parameter enables additional output. Passing debug=0 prints only the
hexadecimal addresses that pprof needs. Passing debug=1 adds comments
translating addresses to function names and line numbers, so that a programmer
can read the profile without tools.

The predefined profiles may assign meaning to other debug values; for example,
when printing the “goroutine” profile, debug=2 means to print the goroutine
stacks in the same form that a Go program uses when dying due to an unrecovered
panic.

Bugs

Subdirectories