procmap

Documentation

Overview

Package procmap resolves addresses into per-binary mapping identity (path, start/limit, file offset, build-id) by parsing /proc/<pid>/maps and ELF .note.gnu.build-id sections. Results feed pprof.Mapping so downstream tools can round-trip samples back to ELF file offsets.

Index

• func ReadBuildID(path string) (string, error)
• type Mapping
• type Option
  • func WithProcRoot(path string) Option
• type Resolver
  • func NewResolver(opts ...Option) *Resolver
  • func (r *Resolver) BuildID(path string) string
  • func (r *Resolver) Close()
  • func (r *Resolver) Invalidate(pid uint32)
  • func (r *Resolver) InvalidateAddr(pid uint32, addr uint64)
  • func (r *Resolver) Lookup(pid uint32, addr uint64) (Mapping, bool)

Functions

func ReadBuildID

func ReadBuildID(path string) (string, error)

ReadBuildID returns the GNU build-id of the ELF at path as a lowercase hex string. Returns an empty string (with nil error) when the ELF is valid but has no .note.gnu.build-id note, and an error when the file can't be opened or isn't ELF.

Types

type Mapping

type Mapping struct {
	Path    string
	Start   uint64
	Limit   uint64 // exclusive
	Offset  uint64 // p_offset of the backing PT_LOAD segment
	BuildID string // hex; empty if no .note.gnu.build-id
	IsExec  bool
}

Mapping describes one executable range in a process's address space. Non-executable and anonymous ranges are dropped during parsing.

type Option

type Option func(*resolverConfig)

Option configures a Resolver.

func WithProcRoot

func WithProcRoot(path string) Option

WithProcRoot overrides the filesystem root used to resolve /proc paths. Defaults to "/proc". Intended for unit tests with fake per-PID fixtures.

type Resolver

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

Resolver caches per-PID /proc/<pid>/maps snapshots and per-path build-ids. Safe for concurrent use. Populates lazily on first Lookup for a PID.

func NewResolver

func NewResolver(opts ...Option) *Resolver

NewResolver returns a Resolver ready for concurrent use.

func (*Resolver) BuildID

func (r *Resolver) BuildID(path string) string

BuildID returns a cached hex build-id for path, reading the ELF on first call. Read failures produce an empty string (cached) — a missing build-id is not a Lookup failure. Safe for concurrent use.

func (*Resolver) Close

func (r *Resolver) Close()

Close releases cached state. After Close, the Resolver remains usable but behaves as freshly constructed; in-flight Lookups that captured a *pidEntry before the call complete normally against their captured snapshot.

func (*Resolver) Invalidate

func (r *Resolver) Invalidate(pid uint32)

Invalidate drops any cached state for pid. The next Lookup re-parses /proc/<pid>/maps. Call on process exit or when the agent learns of whole-process churn (e.g., exec).

func (*Resolver) InvalidateAddr

func (r *Resolver) InvalidateAddr(pid uint32, addr uint64)

InvalidateAddr invalidates pid's cache only if addr falls outside every currently cached mapping — i.e., a new mmap extended the process's address space. Cheap no-op otherwise.

func (*Resolver) Lookup

func (r *Resolver) Lookup(pid uint32, addr uint64) (Mapping, bool)

Lookup returns the Mapping containing addr in pid's address space. Returns ok=false when pid has no cached (or resolvable) mappings, or when addr falls outside every known executable range.