debuginfod

Documentation

Index

• Variables
• type Options
• type Stats
• type Symbolizer
  • func New(opts Options) (*Symbolizer, error)
  • func (s *Symbolizer) Close() error
  • func (s *Symbolizer) Stats() Stats
  • func (s *Symbolizer) SymbolizeProcess(pid uint32, ips []uint64) ([]symbolize.Frame, error)

Variables

var (
	ErrClosed      = errors.New("debuginfod: closed")
	ErrNoURLs      = errors.New("debuginfod: no URLs configured")
	ErrInvalidOpts = errors.New("debuginfod: invalid options")
)

var ErrNotFound = errors.New("debuginfod: not found")

ErrNotFound indicates every configured debuginfod URL returned 404 for the requested build-id.

Types

type Options

type Options struct {
	URLs          []string
	CacheDir      string
	CacheMaxBytes int64
	FetchTimeout  time.Duration
	FailClosed    bool
	Resolver      *procmap.Resolver
	HTTPClient    *http.Client
	Logger        *slog.Logger
	// Demangle is always true in v1. The field exists so we can switch to a
	// *bool tristate later without API breakage.
	Demangle bool
	// InlinedFns is always true in v1. The field exists so we can switch to a
	// *bool tristate later without API breakage.
	InlinedFns bool
	// CodeInfo is always true in v1. The field exists so we can switch to a
	// *bool tristate later without API breakage.
	CodeInfo bool
}

Options configures a Symbolizer. Zero value is invalid; at minimum URLs must be set.

type Stats

type Stats struct {
	CacheHits, CacheMisses, CacheEvictions        uint64
	FetchSuccessDebuginfo, FetchSuccessExecutable uint64
	Fetch404s, FetchErrors                        uint64
	FetchBytesTotal                               uint64
	InFlightFetches                               int64
	DispatcherCalls, DispatcherSkippedLocal       uint64
	DispatcherPanics                              uint64
	// Per-mapping routing (Symbolize-time).
	ClassifyProcessMode, ClassifyFileMode, ClassifySkipped uint64
	// File-mode outcomes.
	// FileModeAddrs is the total number of addresses (IPs) resolved through
	// the file-mode path (one per IP, not one per symbolizeFileBucket call).
	FileModeAddrs, FileModeParseFails     uint64
	FileModeFetchFails, FileModeLocalHits uint64
	// AddressMapper miss for an individual IP.
	NormalizationFails uint64
}

Stats reports operational counters for a Symbolizer. Read via Stats().

type Symbolizer

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

Symbolizer resolves abs addresses against a process while consulting a debuginfod-protocol server for missing debug info. Implements symbolize.Symbolizer.

func New

func New(opts Options) (*Symbolizer, error)

New constructs a Symbolizer from opts. opts.URLs must be non-empty.

func (*Symbolizer) Close

func (s *Symbolizer) Close() error

Close drains in-flight dispatcher invocations, frees blazesym, and closes the cache index. Idempotent.

Order is critical: inflight.Wait() first, so no callback is mid-flight when we tear down the cgo state; cgo.close() next, which frees blazesym (releasing the Rust closure that holds the cb/ctx pair) before deleting the cgo handle; cache.Close() last.

func (*Symbolizer) Stats

func (s *Symbolizer) Stats() Stats

Stats returns a snapshot of operational counters.

func (*Symbolizer) SymbolizeProcess

func (s *Symbolizer) SymbolizeProcess(pid uint32, ips []uint64) ([]symbolize.Frame, error)

SymbolizeProcess resolves abs IPs into Frames. Each address is routed per-mapping:

• skip (only triggered when classify() returns routeSkip — currently rare in practice because procmap.Resolver's parser already filters out pseudo-files ([vdso], [stack], [vsyscall], [heap]) and anonymous ranges upstream; IPs in those regions hit "no mapping found" and fall through to process-mode instead) → empty Frame with the original address so the pprof location's mapping fallback can name it
• process-mode → blazesym's default abs-addr API, with the dispatcher hook handling on-demand fetches of missing executables
• file-mode → AddressMapper translates each IP into a file-VA against the cached .debug, then blazesym's elf-virt API resolves the file-VA and the result's Address is rewritten back to the original IP

Mappings come from procmap.Resolver, whose snapshot excludes pseudo-files such as [vdso]/[stack] and anonymous ranges. IPs in those regions therefore do not hit a separate skip route here; when no mapping is found, they fall back to process-mode.

Failure modes are graceful: a missing AddressMapper translation demotes the individual IP to process-mode; a parse failure of the whole .debug marks the file in badDebug and routes the bucket through process-mode; resolver failure (or no Resolver configured) falls back to pure process-mode for the entire batch. Stack shape is preserved — no frames are dropped — so pprof's mapping resolver can still attach mapping names to every location.