symbolize

Documentation

Overview

Package symbolize provides perf-agent's address-to-frame resolution abstraction. Implementations live in this package (LocalSymbolizer) and in symbolize/debuginfod (off-box-fetch).

Index

• Variables
• func ToProfFrames(frames []Frame) []pprof.Frame
• func ToProfFramesKernel(frames []Frame) []pprof.Frame
• type FailureReason
  • func (r FailureReason) String() string
• type Frame
  • func MergeKernelFirst(kernel, user []Frame) []Frame
• type KernelSymbolizer
• type LocalKernelSymbolizer
  • func NewLocalKernelSymbolizer() (*LocalKernelSymbolizer, error)
  • func (s *LocalKernelSymbolizer) Close() error
  • func (s *LocalKernelSymbolizer) SymbolizeKernel(ips []uint64) ([]Frame, error)
• type LocalSymbolizer
  • func NewLocalSymbolizer() (*LocalSymbolizer, error)
  • func (s *LocalSymbolizer) Close() error
  • func (s *LocalSymbolizer) SymbolizeProcess(pid uint32, ips []uint64) ([]Frame, error)
• type NoopKernelSymbolizer
  • func (NoopKernelSymbolizer) Close() error
  • func (NoopKernelSymbolizer) SymbolizeKernel(ips []uint64) ([]Frame, error)
• type Symbolizer

Variables

var ErrClosed = errors.New("symbolize: closed")

ErrClosed is returned from operations on a closed Symbolizer.

var ErrKernelSymbolsUnavailable = errors.New("symbolize: kernel symbols unavailable (kptr_restrict?)")

ErrKernelSymbolsUnavailable indicates /proc/kallsyms is unreadable or kptr-restricted (kernel addresses come back as zeros). Callers SHOULD construct a NoopKernelSymbolizer and continue rather than fail.

Functions

func ToProfFrames

func ToProfFrames(frames []Frame) []pprof.Frame

ToProfFrames flattens a []Frame (each with optional Inlined chain) into a leaf-first []pprof.Frame for direct insertion into pprof builders.

blazesym reports Inlined caller-most-to-callee; pprof wants leaf-first. Each frame in a chain shares the outer Frame's Address so pprof's Locations stay distinguishable when two PCs symbolize identically.

func ToProfFramesKernel

func ToProfFramesKernel(frames []Frame) []pprof.Frame

ToProfFramesKernel is ToProfFrames + IsKernel=true on every output frame. pprof.ProfileBuilder routes IsKernel frames through the existing kernelSentinel mapping at pprof/pprof.go:288 — no builder code changes needed. Used by every call site that converts symbolized kernel frames to pprof.Frame.

Types

type FailureReason

type FailureReason uint8

FailureReason describes why a Frame's Name is empty.

const (
	FailureNone FailureReason = iota
	FailureUnmapped
	FailureInvalidFileOffset
	FailureMissingComponent
	FailureMissingSymbols
	FailureUnknownAddress
	FailureFetchError
	FailureNoBuildID
)

func (FailureReason) String

func (r FailureReason) String() string

type Frame

type Frame struct {
	Address uint64
	Name    string
	Module  string
	BuildID string
	File    string
	Line    int
	Column  int
	Offset  uint64
	Inlined []Frame
	Reason  FailureReason
}

Frame is a single symbolized stack frame. Name is "" when resolution failed; Reason explains why. Inlined holds the inline-expansion chain in caller-most-to-callee order when the resolver supports it.

func MergeKernelFirst

func MergeKernelFirst(kernel, user []Frame) []Frame

MergeKernelFirst returns a leaf-first frame chain by prepending kernel frames (already leaf-first per blazesym convention) onto user frames. Either slice may be nil.

type KernelSymbolizer

type KernelSymbolizer interface {
	SymbolizeKernel(ips []uint64) ([]Frame, error)
	Close() error
}

KernelSymbolizer resolves kernel-mode addresses to symbolic frames. Kernel-mode resolution has no PID — kernel + module symbols are global. Implementations are safe for concurrent use.

type LocalKernelSymbolizer

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

LocalKernelSymbolizer wraps blazesym's kernel source: /proc/kallsyms for vmlinux + every loaded module's symbols. With debug_syms=true and the v1.1.0+ blazesym pin (≥ commit 29a609f), module functions resolve to function name + source :line when distro kernel-modules-debuginfo is installed locally.

func NewLocalKernelSymbolizer

func NewLocalKernelSymbolizer() (*LocalKernelSymbolizer, error)

NewLocalKernelSymbolizer returns a kernel symbolizer or ErrKernelSymbolsUnavailable when /proc/kallsyms is unreadable or kptr-restricted (first symbol address is 0).

func (*LocalKernelSymbolizer) Close

func (s *LocalKernelSymbolizer) Close() error

Close releases the underlying blazesym symbolizer. Idempotent.

func (*LocalKernelSymbolizer) SymbolizeKernel

func (s *LocalKernelSymbolizer) SymbolizeKernel(ips []uint64) ([]Frame, error)

SymbolizeKernel resolves kernel addresses via blazesym's kernel source. Returns one Frame per IP. Frames whose name couldn't be resolved get Name = "0x<hex>" + Reason = FailureMissingSymbols (matches Noop posture).

type LocalSymbolizer

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

LocalSymbolizer wraps blazesym's Process source with no off-box hooks — preserves perf-agent's pre-debuginfod behavior. Used when no debuginfod URL is configured.

func NewLocalSymbolizer

func NewLocalSymbolizer() (*LocalSymbolizer, error)

NewLocalSymbolizer constructs a LocalSymbolizer with code-info and inlined-fns enabled (matches today's behavior at the three call sites).

func (*LocalSymbolizer) Close

func (s *LocalSymbolizer) Close() error

Close releases the underlying blazesym Symbolizer. Idempotent.

func (*LocalSymbolizer) SymbolizeProcess

func (s *LocalSymbolizer) SymbolizeProcess(pid uint32, ips []uint64) ([]Frame, error)

SymbolizeProcess returns one Frame per IP. blazesym's Inlined chain is expanded into the Frame.Inlined slice in caller-most-to-callee order.

type NoopKernelSymbolizer

type NoopKernelSymbolizer struct{}

NoopKernelSymbolizer returns a Frame per IP with Name = "0x<hex>" and Reason = FailureMissingSymbols. Used when --kernel-stacks is off, or when /proc/kallsyms is locked down.

func (NoopKernelSymbolizer) Close

func (NoopKernelSymbolizer) Close() error

Close is a no-op.

func (NoopKernelSymbolizer) SymbolizeKernel

func (NoopKernelSymbolizer) SymbolizeKernel(ips []uint64) ([]Frame, error)

SymbolizeKernel returns one Frame per input IP with the address rendered as a hex string in Name. Address is preserved so pprof Locations stay distinguishable.

type Symbolizer

type Symbolizer interface {
	SymbolizeProcess(pid uint32, ips []uint64) ([]Frame, error)
	Close() error
}

Symbolizer resolves abs addresses in a process's address space to symbolic frames. Implementations are safe for concurrent use.