profile

Documentation

Index

• type OffCPUDwarf
  • func LoadOffCPUDwarf(systemWide, kernelStacks bool) (*OffCPUDwarf, error)
  • func (p *OffCPUDwarf) AddPID(pid uint32) error
  • func (p *OffCPUDwarf) CFIClassificationLengthsMap() *ebpf.Map
  • func (p *OffCPUDwarf) CFIClassificationMap() *ebpf.Map
  • func (p *OffCPUDwarf) CFILengthsMap() *ebpf.Map
  • func (p *OffCPUDwarf) CFIRulesMap() *ebpf.Map
  • func (p *OffCPUDwarf) Close() error
  • func (p *OffCPUDwarf) KernStackmap() *ebpf.Map
  • func (p *OffCPUDwarf) PIDMappingLengthsMap() *ebpf.Map
  • func (p *OffCPUDwarf) PIDMappingsMap() *ebpf.Map
  • func (p *OffCPUDwarf) Program() *ebpf.Program
  • func (p *OffCPUDwarf) RingbufMap() *ebpf.Map
• type PerfDwarf
  • func LoadPerfDwarf(systemWide, kernelStacks bool) (*PerfDwarf, error)
  • func (p *PerfDwarf) AddPID(pid uint32) error
  • func (p *PerfDwarf) CFIClassificationLengthsMap() *ebpf.Map
  • func (p *PerfDwarf) CFIClassificationMap() *ebpf.Map
  • func (p *PerfDwarf) CFILengthsMap() *ebpf.Map
  • func (p *PerfDwarf) CFIMissRatelimitMap() *ebpf.Map
  • func (p *PerfDwarf) CFIMissRingbuf() *ebpf.Map
  • func (p *PerfDwarf) CFIRulesMap() *ebpf.Map
  • func (p *PerfDwarf) Close() error
  • func (p *PerfDwarf) KernStackmap() *ebpf.Map
  • func (p *PerfDwarf) PIDMappingLengthsMap() *ebpf.Map
  • func (p *PerfDwarf) PIDMappingsMap() *ebpf.Map
  • func (p *PerfDwarf) Program() *ebpf.Program
  • func (p *PerfDwarf) RingbufMap() *ebpf.Map
  • func (p *PerfDwarf) SetSystemWide(v bool) error
• type Profiler
  • func NewProfiler(pid int, systemWide bool, cpus []uint, tags []string, sampleRate int, ...) (*Profiler, error)
  • func (pr *Profiler) Close()
  • func (pr *Profiler) Collect(w io.Writer) error
  • func (pr *Profiler) CollectAndWrite(outputPath string) error

Types

type OffCPUDwarf

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

OffCPUDwarf is a thin wrapper around the generated offcpu_dwarf BPF objects. Construct with LoadOffCPUDwarf; always Close() when done.

func LoadOffCPUDwarf

func LoadOffCPUDwarf(systemWide, kernelStacks bool) (*OffCPUDwarf, error)

LoadOffCPUDwarf loads the BPF program and returns a handle. Caller must Close(). The tp_btf/sched_switch program isn't attached yet — see unwind/dwarfagent.OffCPUProfiler for the attach wiring via link.AttachTracing.

kernelStacks gates the BPF program's kernel-stack capture (set from cfg.KernelStacks). When false, kernel-stack capture is fully bypassed at sample time; the CollectKernel bit on each pid_config entry is a no-op. When true, kernel stacks are captured for matched samples.

func (*OffCPUDwarf) AddPID

func (p *OffCPUDwarf) AddPID(pid uint32) error

AddPID registers a target PID for sampling. Semantics match profile.PerfDwarf.AddPID — inserts into the `pids` filter.

func (*OffCPUDwarf) CFIClassificationLengthsMap

func (p *OffCPUDwarf) CFIClassificationLengthsMap() *ebpf.Map

CFIClassificationLengthsMap returns the cfi_classification_lengths HASH.

func (*OffCPUDwarf) CFIClassificationMap

func (p *OffCPUDwarf) CFIClassificationMap() *ebpf.Map

CFIClassificationMap returns the cfi_classification HASH_OF_MAPS outer map.

func (*OffCPUDwarf) CFILengthsMap

func (p *OffCPUDwarf) CFILengthsMap() *ebpf.Map

CFILengthsMap returns the cfi_lengths HASH keyed by table_id → u32 length.

func (*OffCPUDwarf) CFIRulesMap

func (p *OffCPUDwarf) CFIRulesMap() *ebpf.Map

CFIRulesMap returns the cfi_rules HASH_OF_MAPS outer map.

func (*OffCPUDwarf) Close

func (p *OffCPUDwarf) Close() error

Close releases all BPF objects.

func (*OffCPUDwarf) KernStackmap

func (p *OffCPUDwarf) KernStackmap() *ebpf.Map

KernStackmap returns the BPF_MAP_TYPE_STACK_TRACE used for kernel stack-ID lookup. Populated only when kernel_stacks_enabled is true at BPF load; otherwise samples carry KernStack == -1 and userspace skips the lookup. Mirror of FP off-CPU profiler's Stackmap accessor.

func (*OffCPUDwarf) PIDMappingLengthsMap

func (p *OffCPUDwarf) PIDMappingLengthsMap() *ebpf.Map

PIDMappingLengthsMap returns the pid_mapping_lengths HASH keyed by pid → u32 length.

func (*OffCPUDwarf) PIDMappingsMap

func (p *OffCPUDwarf) PIDMappingsMap() *ebpf.Map

PIDMappingsMap returns the pid_mappings HASH_OF_MAPS outer map.

func (*OffCPUDwarf) Program

func (p *OffCPUDwarf) Program() *ebpf.Program

Program returns the tp_btf/sched_switch program. Attach via link.AttachTracing (not link.AttachRawLink — this isn't a perf_event).

func (*OffCPUDwarf) RingbufMap

func (p *OffCPUDwarf) RingbufMap() *ebpf.Map

RingbufMap returns the stack_events ringbuf for ringbuf.NewReader.

type PerfDwarf

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

PerfDwarf is a thin wrapper around the generated perf_dwarf BPF objects. Construct with LoadPerfDwarf; always Close() when done.

func LoadPerfDwarf

func LoadPerfDwarf(systemWide, kernelStacks bool) (*PerfDwarf, error)

LoadPerfDwarf loads the BPF program and returns a handle. Caller must Close(). The program isn't attached to any perf event yet — the caller opens perf_event_open fds and attaches separately (see unwind/dwarfagent for the full wiring).

kernelStacks gates the BPF program's kernel-stack capture (set from cfg.KernelStacks). When false, kernel-stack capture is fully bypassed at sample time; the CollectKernel bit on each pid_config entry is a no-op. When true, kernel stacks are captured for matched samples.

func (*PerfDwarf) AddPID

func (p *PerfDwarf) AddPID(pid uint32) error

AddPID registers a target PID for sampling. Matches the semantics of profile.Profiler's PID filter in targeted mode.

func (*PerfDwarf) CFIClassificationLengthsMap

func (p *PerfDwarf) CFIClassificationLengthsMap() *ebpf.Map

CFIClassificationLengthsMap returns the cfi_classification_lengths HASH.

func (*PerfDwarf) CFIClassificationMap

func (p *PerfDwarf) CFIClassificationMap() *ebpf.Map

CFIClassificationMap returns the cfi_classification HASH_OF_MAPS outer map.

func (*PerfDwarf) CFILengthsMap

func (p *PerfDwarf) CFILengthsMap() *ebpf.Map

CFILengthsMap returns the cfi_lengths HASH keyed by table_id → u32 length.

func (*PerfDwarf) CFIMissRatelimitMap

func (p *PerfDwarf) CFIMissRatelimitMap() *ebpf.Map

CFIMissRatelimitMap returns the per-(pid, table_id) rate-limit map. Exposed for tests that want to introspect the rate-limit state; not needed by the production path.

func (*PerfDwarf) CFIMissRingbuf

func (p *PerfDwarf) CFIMissRingbuf() *ebpf.Map

CFIMissRingbuf returns the ringbuf the BPF walker writes lazy-CFI miss notifications to. Userspace drains this in lazy mode (--unwind auto).

func (*PerfDwarf) CFIRulesMap

func (p *PerfDwarf) CFIRulesMap() *ebpf.Map

CFIRulesMap returns the cfi_rules HASH_OF_MAPS outer map.

func (*PerfDwarf) Close

func (p *PerfDwarf) Close() error

Close releases all BPF objects.

func (*PerfDwarf) KernStackmap

func (p *PerfDwarf) KernStackmap() *ebpf.Map

KernStackmap returns the BPF_MAP_TYPE_STACK_TRACE used for kernel stack-ID lookup. Populated only when kernel_stacks_enabled is true at BPF load; otherwise samples carry KernStack == -1 and userspace skips the lookup. Mirror of FP profiler's Stackmap accessor.

func (*PerfDwarf) PIDMappingLengthsMap

func (p *PerfDwarf) PIDMappingLengthsMap() *ebpf.Map

PIDMappingLengthsMap returns the pid_mapping_lengths HASH keyed by pid → u32 length.

func (*PerfDwarf) PIDMappingsMap

func (p *PerfDwarf) PIDMappingsMap() *ebpf.Map

PIDMappingsMap returns the pid_mappings HASH_OF_MAPS outer map.

func (*PerfDwarf) Program

func (p *PerfDwarf) Program() *ebpf.Program

Program returns the PerfDwarf program for attaching to a perf_event_open fd.

func (*PerfDwarf) RingbufMap

func (p *PerfDwarf) RingbufMap() *ebpf.Map

RingbufMap returns the stack_events ringbuf for ringbuf.NewReader.

func (*PerfDwarf) SetSystemWide

func (p *PerfDwarf) SetSystemWide(v bool) error

SetSystemWide is a no-op; the setting is baked in at load time via the systemWide argument to LoadPerfDwarf. Kept as a stable API placeholder.

type Profiler

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

Profiler handles CPU profiling with stack traces

func NewProfiler

func NewProfiler(pid int, systemWide bool, cpus []uint, tags []string, sampleRate int, labels map[string]string, perfData *perfdata.Writer, eventSpec *perfevent.EventSpec, sym symbolize.Symbolizer, kernelSym symbolize.KernelSymbolizer, kernelStacks bool) (*Profiler, error)

NewProfiler creates a new CPU profiler.

eventSpec selects the perf-event source. Pass nil to default to software cpu-clock at sampleRate Hz. When non-nil, sampleRate is ignored (the caller is responsible for putting the desired rate in eventSpec). Used by the agent to keep the in-kernel event and the perf.data attr in sync when the output writer is enabled — a divergence would mislead consumers.

kernelStacks gates the BPF program's kernel-stack capture (set from cfg.KernelStacks). When false, kernel-stack capture is fully bypassed at sample time; the CollectKernel bit on each pid_config entry is a no-op. When true, kernel stacks are captured for matched samples.

func (*Profiler) Close

func (pr *Profiler) Close()

Close releases all resources associated with the profiler. The symbolizer is owned by the Agent; we do not close it here.

func (*Profiler) Collect

func (pr *Profiler) Collect(w io.Writer) error

Collect writes the profile to the provided writer (supports streaming). The output is gzip-compressed pprof data.

func (*Profiler) CollectAndWrite

func (pr *Profiler) CollectAndWrite(outputPath string) error

CollectAndWrite collects samples and writes the profile to the specified path. This is a convenience wrapper around Collect for file-based output.