Package pprof

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

var cpuprofile = flag.String("cpuprofile", "", "write cpu profile to `file`")
var memprofile = flag.String("memprofile", "", "write memory profile to `file`")

func main() {
    flag.Parse()
    if *cpuprofile != "" {
        f, err := os.Create(*cpuprofile)
        if err != nil {
            log.Fatal("could not create CPU profile: ", err)
        }
        defer f.Close() // error handling omitted for example
        if err := pprof.StartCPUProfile(f); err != nil {
            log.Fatal("could not start CPU profile: ", err)
        }
        defer pprof.StopCPUProfile()
    }

    // ... rest of the program ...

    if *memprofile != "" {
        f, err := os.Create(*memprofile)
        if err != nil {
            log.Fatal("could not create memory profile: ", err)
        }
        defer f.Close() // error handling omitted for example
        runtime.GC() // get up-to-date statistics
        // Lookup("allocs") creates a profile similar to go test -memprofile.
        // Alternatively, use Lookup("heap") for a profile
        // that has inuse_space as the default index.
        if err := pprof.Lookup("allocs").WriteTo(f, 0); err != nil {
            log.Fatal("could not write memory profile: ", err)
        }
    }
}

import _ "net/http/pprof"

go tool pprof cpu.prof

func Do

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. Goroutines spawned while executing f will inherit the augmented label-set. 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

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

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 SetGoroutineLabels

func SetGoroutineLabels(ctx context.Context)

SetGoroutineLabels sets the current goroutine's labels to match ctx. A new goroutine inherits the labels of the goroutine that created it. This is a lower-level API than Do, which should be used instead when possible.

func StartCPUProfile

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

func StopCPUProfile()

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

func WithLabels

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

func WriteHeapProfile(w io.Writer) error

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

type LabelSet

LabelSet is a set of labels.

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

func Labels

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. Currently only the CPU and goroutine profiles utilize any labels information. See https://golang.org/issue/23458 for details.

type Profile

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

func Lookup

func Lookup(name string) *Profile

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

func NewProfile

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 Profiles

func Profiles() []*Profile

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

func (*Profile) Add

func (p *Profile) Add(value any, 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 Profile.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

func (p *Profile) Count() int

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

func (*Profile) Name

func (p *Profile) Name() string

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

func (*Profile) Remove

func (p *Profile) Remove(value any)

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

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 writes the gzip-compressed protocol buffer described in https://github.com/google/pprof/tree/main/proto#overview. Passing debug=1 writes the legacy text format with 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

• ☞

  Profiles are only as good as the kernel support used to generate them. See https://golang.org/issue/13841 for details about known problems.