perfagent

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

type Config struct {
	// PID is the target process ID to monitor (0 for system-wide).
	PID int

	// SystemWide enables system-wide profiling of all processes.
	SystemWide bool

	// EnableCPUProfile enables CPU profiling with stack traces.
	EnableCPUProfile bool

	// CPUProfilePath is the output path for CPU profiles.
	CPUProfilePath string

	// CPUProfileWriter is an optional writer for CPU profile output.
	// If set, profile data is written here instead of to CPUProfilePath.
	CPUProfileWriter io.Writer

	// EnableOffCPUProfile enables off-CPU profiling with stack traces.
	EnableOffCPUProfile bool

	// OffCPUProfilePath is the output path for off-CPU profiles.
	OffCPUProfilePath string

	// OffCPUProfileWriter is an optional writer for off-CPU profile output.
	// If set, profile data is written here instead of to OffCPUProfilePath.
	OffCPUProfileWriter io.Writer

	// PerfDataOutput is the path for a kernel-format perf.data file. Empty
	// disables emission. Set via WithPerfDataOutput. Only on-CPU samples
	// are written; off-CPU and PMU modes ignore this option.
	PerfDataOutput string

	// EnablePMU enables PMU hardware counter monitoring.
	EnablePMU bool

	// PerPID shows per-PID breakdown in system-wide mode.
	PerPID bool

	// SampleRate is the CPU profiling sample rate in Hz.
	SampleRate int

	// Tags are key=value pairs to add to profiles.
	Tags []string

	// MetricsExporters are the exporters to use for metrics output.
	MetricsExporters []metrics.Exporter

	// Unwind selects the stack unwinding strategy for --profile and
	// --offcpu modes. Valid values: "fp" (frame pointer),
	// "dwarf" (DWARF CFI), "auto" (default; aliases to "dwarf",
	// and the DWARF walker already takes the FP path for FP-safe
	// frames). After options parsing, an empty string is treated
	// as "auto".
	Unwind string

	// CPUs is the list of CPUs to monitor. If nil, all online CPUs are used.
	CPUs []uint

	// InjectPython enables Python perf-trampoline injection during profiling.
	// Only valid with EnableCPUProfile. Requires CAP_SYS_PTRACE.
	InjectPython bool

	// Labels are static per-sample pprof labels. Merged on top of the enricher
	// output (Labels wins on key collision). Set via WithLabels.
	Labels map[string]string

	// LabelEnricher computes additional per-sample labels at agent startup
	// from the resolved host PID. Default is internal/k8slabels.FromPID.
	// Override via WithLabelEnricher; pass nil to disable defaults entirely.
	// LabelEnricherSet records whether the user explicitly called
	// WithLabelEnricher (so passing nil to disable is distinguishable from
	// not calling it at all).
	LabelEnricher    func(hostPID int) map[string]string
	LabelEnricherSet bool

	// DebuginfodURLs is the ordered list of debuginfod servers to consult for
	// off-box DWARF/executable fetching. If empty (and DEBUGINFOD_URLS env is
	// also empty), the agent uses the local symbolizer.
	DebuginfodURLs []string

	// SymbolCacheDir overrides the debuginfod cache directory.
	// Default: /tmp/perf-agent-debuginfod.
	SymbolCacheDir string

	// SymbolCacheMaxBytes overrides the debuginfod cache size cap. Default: 2 GiB.
	SymbolCacheMaxBytes int64

	// SymbolFetchTimeout overrides per-artifact fetch timeout. Default: 30s.
	SymbolFetchTimeout time.Duration

	// SymbolFailClosed makes the agent refuse to symbolize a mapping whose
	// debuginfod fetch failed (vs. fall back to local). Default: false.
	// Note: M1 ships the option but FailClosed semantics are M2.
	SymbolFailClosed bool

	// KernelStacks enables kernel-mode stack capture and symbolization.
	// Default: false. Opt in via --kernel-stacks (CLI) or
	// WithKernelStacks() (library).
	//
	// When set:
	//   - BPF programs enable the kernel-stack capture path (a volatile
	//     bool global flipped at load time; no per-sample cost when off).
	//   - The Agent constructs a LocalKernelSymbolizer; on
	//     ErrKernelSymbolsUnavailable, falls back to NoopKernelSymbolizer
	//     + a one-time warning.
	//   - --perf-data-output emits a kernel MMAP2 record at writer init,
	//     and SampleRecord callchains carry PERF_CONTEXT_{KERNEL,USER}
	//     markers around the merged kernel+user IPs.
	KernelStacks bool
}

type Option func(*Config)