pprofutils

README

pprofutils

pprofutils provides command line utilities for converting pprof files to Brendan Gregg's folded text format (output by his stackcollapse scripts) and vice versa.

Install

pprofutils requires Go 1.16 and can be installed like this:

go install github.com/felixge/pprofutils/cmd/...@latest

Usage

Convert a pprof file to folded stack text:

pprof2text < ./test-fixtures/pprof.samples.cpu.001.pb.gz > example.txt

Convert a folded stack text file to pprof:

text2pprof < example.txt > example.pprof

Warning: Converting from pprof to text is lossy. Only the first sample type will be converted, file names, lines, labels, and more will be dropped. Patches to make things less lossy would be welcome, but please open an issue first to discuss.

Convert a Linux perf.data profile to pprof, via Brendan Gregg's stackcollapse-perf.pl script:

perf script | stackcollapse-perf.pl | text2pprof > perf.pprof

Create a delta profile that contains the difference heap-b.pprof - heap-a.pprof:

pprofdelta -o delta.pprof heap-a.pprof heap-b.pprof

Tutorial: Generate a fake pprof profile

My primary use case for this tool is to quickly generate fake pprof profiles for creating educational content.

This can be done by simply creating a file called profile.txt with the following content:

main;foo 5
main;foo;bar 3
main;foobar 4

Then convert it to a pprof profile:

text2pprof < profile.txt > profile.pprof

And finally view it using pprof:

go tool pprof -http=:6060 profile.pprof

The resulting graphs should look like this:

Custom Extension: Multiple Sample Types

The text2pprof command supports a custom extension to the folded text format that allows users to specify multiple sample types.

This is done via a header that contains space separated type/unit sample types. The stack traces on the following lines must then contain one value for each sample type after the stack trace:

samples/count duration/nanoseconds
main;foo 5 50000000
main;foo;bar 3 30000000
main;foobar 4 40000000

The pprof2text command also supports outputting this format by passing the -m flag.

License

pprofutils is licensed under the MIT License.

Documentation

Index

• type Delta
  • func (d Delta) Convert(a, b *profile.Profile) (*profile.Profile, error)
• type Protobuf
  • func (p Protobuf) Convert(protobuf *profile.Profile, text io.Writer) error
• type Text
  • func (c Text) Convert(text io.Reader) (*profile.Profile, error)
• type ValueType

Types

type Delta

type Delta struct {
	// SampleTypes limits the delta calcultion to the given sample types. Other
	// sample types will retain the values of profile b. The defined sample types
	// must exist in the profile, otherwise derivation will fail with an error.
	// If the slice is empty, all sample types are subject to delta profile
	// derivation.
	//
	// The use case for this for this is to deal with the heap profile which
	// contains alloc and inuse sample types, but delta profiling makes no sense
	// for the latter.
	SampleTypes []ValueType
}

Delta describes how to compute the delta between two profiles and implements the conversion.

func (Delta) Convert

func (d Delta) Convert(a, b *profile.Profile) (*profile.Profile, error)

Delta computes the delta between all values b-a and returns them as a new profile. Samples that end up with a delta of 0 are dropped. WARNING: Profile a will be mutated by this function. You should pass a copy if that's undesirable.

type Protobuf

type Protobuf struct {
	// SampleTypes causes the text output to begin with a header line listing
	// the sample types found in the profile. This is a custom extension to the
	// folded text format.
	SampleTypes bool
}

Protobuf converts from pprof's protobuf to folded text format.

func (Protobuf) Convert

func (p Protobuf) Convert(protobuf *profile.Profile, text io.Writer) error

Convert marshals the given protobuf profile into folded text format.

type Text

type Text struct{}

Text converts from folded text to protobuf format.

func (Text) Convert

func (c Text) Convert(text io.Reader) (*profile.Profile, error)

Convert parses the given text and returns it as protobuf profile.

type ValueType

type ValueType struct {
	Type string
	Unit string
}

ValueType describes the type and unit of a value.