perfevent

Documentation

Overview

Package perfevent opens per-CPU software perf_event_open events and attaches a BPF program to each. It exists to deduplicate the boilerplate that profile.NewProfiler and dwarfagent.NewProfilerWithMode each used to spell out independently — same PerfEventAttr, same per-CPU loop, same "tolerate ESRCH on offline CPU" rule, same cleanup-on-error.

Probes the kernel for the most accurate sample event available, falling back gracefully when running in environments (cloud VMs, k8s pods on virtualized hosts) where hardware PMU events aren't exposed.

Index

• Constants
• type EventSpec
  • func ProbeHardwareCycles(sampleHz uint64) (EventSpec, error)
  • func (s EventSpec) String() string
• type Option
  • func WithDeferredEnable() Option
• type Set
  • func OpenAll(prog *ebpf.Program, cpus []uint, spec EventSpec, opts ...Option) (*Set, error)
  • func (s *Set) Close() error
  • func (s *Set) FDs() []int

Constants

const (
	PerfTypeHardware = 0
	PerfTypeSoftware = 1

	PerfCountHWCPUCycles = 0
	PerfCountSWCPUClock  = 0
)

Types

type EventSpec

type EventSpec struct {
	Type         uint32
	Config       uint64
	SamplePeriod uint64
	Frequency    bool
}

EventSpec is the perf-event configuration used to open per-CPU events AND to populate the perf.data attr section. SamplePeriod is interpreted as a frequency (Hz) when Frequency is true.

func ProbeHardwareCycles

func ProbeHardwareCycles(sampleHz uint64) (EventSpec, error)

ProbeHardwareCycles tries to open a PERF_TYPE_HARDWARE / PERF_COUNT_HW_CPU_CYCLES event; on success returns that EventSpec. On the typical virtualized-host failures (EOPNOTSUPP, ENOENT, ENODEV, EINVAL, EACCES) it returns the software cpu-clock fallback. Any other error propagates — those usually mean broken kernel state we shouldn't paper over.

sampleHz is the desired sample rate; threaded through into the returned EventSpec.SamplePeriod with Frequency=true.

func (EventSpec) String

func (s EventSpec) String() string

type Option

type Option func(*config)

Option configures OpenAll.

func WithDeferredEnable

func WithDeferredEnable() Option

WithDeferredEnable opens each event disabled and enables it after the BPF program is attached. Recommended for new call sites.

type Set

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

Set is a bundle of per-CPU perf events with their attached BPF links. Close releases everything in the right order; safe to call once.

func OpenAll

func OpenAll(prog *ebpf.Program, cpus []uint, spec EventSpec, opts ...Option) (*Set, error)

OpenAll opens one perf event per CPU configured per spec (Type/Config determine the event source; SamplePeriod is interpreted as a frequency in Hz when spec.Frequency is true, otherwise as a fixed sample period), attaches prog to each via link.AttachRawLink, and returns the resulting Set.

Offline CPUs (ESRCH from perf_event_open) are skipped silently — they come back online or stay offline, neither is an error here. If every CPU is offline / no event was attached, OpenAll returns an error.

On any failure mid-loop, every fd and link opened so far is released before returning. Caller never has to clean up after a non-nil error.

func (*Set) Close

func (s *Set) Close() error

Close closes every attached link and then every fd. Errors are best-effort — the first non-nil error is returned, but cleanup proceeds regardless.

func (*Set) FDs

func (s *Set) FDs() []int

FDs returns the underlying perf_event file descriptors. Callers should treat the returned slice as read-only — the Set still owns these fds and will close them via Close. Used by collectors that need to read counter values directly (currently none, but PMU-side collectors might).