profileconv

Documentation

Overview

Package profileconv parses pprof profiles into a hierarchical flame tree suitable for visualisation in the UI.

Index

• func BuildFlame(data []byte, valueIndex int) (*chstore.FlameNode, error)
• func BuildFlameAuto(data []byte) (*chstore.FlameNode, error)
• func BuildFlameFromCollapsed(data []byte) (*chstore.FlameNode, error)
• func IsPprof(data []byte) bool
• func MergeFlame(dst, src *chstore.FlameNode)
• func SampleCount(data []byte) (int, error)
• type CategoryBreakdown
  • func FlameCategoryBreakdown(root *chstore.FlameNode) CategoryBreakdown
  • func (b CategoryBreakdown) Total() int64
• type FrameKind
  • func ClassifyFrame(name string) FrameKind
• type MethodHotspot
  • func FlameToHotspots(root *chstore.FlameNode) []MethodHotspot

Functions

func BuildFlame

func BuildFlame(data []byte, valueIndex int) (*chstore.FlameNode, error)

BuildFlame parses raw pprof bytes (gzip or plain pb) and aggregates samples into a flame graph tree. `valueIndex` selects which sample value to use: 0 is the default (first value, e.g. CPU samples or alloc count).

func BuildFlameAuto

func BuildFlameAuto(data []byte) (*chstore.FlameNode, error)

BuildFlameAuto picks the right parser based on the payload format.

func BuildFlameFromCollapsed

func BuildFlameFromCollapsed(data []byte) (*chstore.FlameNode, error)

BuildFlameFromCollapsed parses async-profiler "collapsed" output:

frame_root;frame_b;frame_c 142
frame_root;frame_b;frame_d 88

Each line is one stack (root → leaf, semi-colon separated) followed by a count. The same stack may repeat across lines; counts accumulate.

func IsPprof

func IsPprof(data []byte) bool

IsPprof returns true if the byte slice looks like a pprof payload (gzipped protobuf — magic bytes 0x1f 0x8b — or raw protobuf wire format). Anything else is treated as collapsed-stack text format.

func MergeFlame

func MergeFlame(dst, src *chstore.FlameNode)

MergeFlame folds src into dst in place — sums Value+Self on every (name, file, line)-matched node and recursively merges children. dst's Name is unchanged (callers seed a synthetic "root" node). Used by the service-level hotspot aggregator where N pprof samples in a time window need to look like one flame tree.

func SampleCount

func SampleCount(data []byte) (int, error)

SampleCount estimates how many samples a profile contains (for display).

Types

type CategoryBreakdown

type CategoryBreakdown struct {
	CPU   int64 `json:"cpu"`
	Lock  int64 `json:"lock"`
	IO    int64 `json:"io"`
	Sleep int64 `json:"sleep"`
	GC    int64 `json:"gc"`
}

CategoryBreakdown is the total self-time per FrameKind across the whole flame. Sums equal the flame's root value (each sample lands in exactly one bucket via its leaf frame).

func FlameCategoryBreakdown

func FlameCategoryBreakdown(root *chstore.FlameNode) CategoryBreakdown

FlameCategoryBreakdown attributes each frame's Self to its FrameKind. Walks the whole tree — internal frames with Self=0 contribute nothing, so the sum tracks the leaf-time distribution exactly.

func (CategoryBreakdown) Total

func (b CategoryBreakdown) Total() int64

type FrameKind

type FrameKind string

FrameKind classifies a stack frame by what the runtime was doing while sampled there. Dynatrace's "Suspension" panel reads off exactly this distinction — a 10s self-time on a CPU frame is a hot path worth optimising, the same 10s on a LockSupport.park is contention and the operator looks elsewhere. Default for any frame we don't recognise is FrameCPU.

const (
	FrameCPU   FrameKind = "cpu"
	FrameLock  FrameKind = "lock"  // park, wait, mutex acquire
	FrameIO    FrameKind = "io"    // network / disk syscall
	FrameSleep FrameKind = "sleep" // explicit Thread.sleep / time.Sleep
	FrameGC    FrameKind = "gc"    // runtime GC overhead
)

func ClassifyFrame

func ClassifyFrame(name string) FrameKind

ClassifyFrame returns the FrameKind for a fully qualified method/function name. Rules are conservative — false positives on the kind badge confuse operators, so we only match well- known framework / runtime call sites. Anything not on the list stays FrameCPU (the safe default).

type MethodHotspot

type MethodHotspot struct {
	Name  string    `json:"name"`
	File  string    `json:"file,omitempty"`
	Line  int64     `json:"line,omitempty"`
	Self  int64     `json:"self"`
	Total int64     `json:"total"`
	Paths int       `json:"paths"`
	Kind  FrameKind `json:"kind"`
}

MethodHotspot is the per-function rollup the API returns to the UI. Self / Total / Paths semantics mirror the frontend helper (flameHotspots.ts) so the table looks identical whether it's fed by a single profile or a merged window. Kind annotates the row (cpu/lock/io/sleep/gc) so the UI can render a coloured badge — operators chasing a regression can scan-skip lock/sleep rows when looking for CPU hot paths.

func FlameToHotspots

func FlameToHotspots(root *chstore.FlameNode) []MethodHotspot

FlameToHotspots walks the tree once, accumulating per-name stats. Recursion-safe: a name's Total is credited only once per stack so self-recursive functions don't double-count.