perfdata

Documentation

Overview

Package perfdata writes Linux kernel perf.data files. The on-disk format is documented in tools/perf/Documentation/perf.data-file-format.txt in the Linux kernel tree. perf.data is little-endian on every supported architecture, so we hardcode that here.

Index

• type BuildIDEntry
• type CommRecord
• type EventSpec
• type MetaInfo
• type Mmap2Record
• type SampleRecord
• type Writer
  • func Open(path string, spec EventSpec, meta MetaInfo) (*Writer, error)
  • func (w *Writer) AddBuildID(e BuildIDEntry)
  • func (w *Writer) AddComm(r CommRecord)
  • func (w *Writer) AddFinishedRound()
  • func (w *Writer) AddKernelMmap() error
  • func (w *Writer) AddMmap2(r Mmap2Record)
  • func (w *Writer) AddSample(r SampleRecord)
  • func (w *Writer) Close() error

Types

type BuildIDEntry

type BuildIDEntry struct {
	Pid      int32
	BuildID  [20]byte
	Filename string
}

BuildIDEntry is one entry in the HEADER_BUILD_ID feature section. Pid = -1 means "kernel or any process" (kernel mappings); other values are actual host PIDs.

type CommRecord

type CommRecord struct {
	Pid  uint32
	Tid  uint32
	Comm string
}

CommRecord is the in-memory image of a PERF_RECORD_COMM payload.

type EventSpec

type EventSpec struct {
	Type         uint32 // PERF_TYPE_*
	Config       uint64 // event-type-specific
	SamplePeriod uint64 // period (or freq Hz when Frequency = true)
	Frequency    bool   // whether SamplePeriod is a frequency
}

EventSpec describes the perf event the captured samples come from. Filled from internal/perfevent's auto-detect probe.

type MetaInfo

type MetaInfo struct {
	Hostname  string
	OSRelease string
	NumCPUs   uint32
}

MetaInfo captures host-level facts the writer stamps into feature sections.

type Mmap2Record

type Mmap2Record struct {
	Pid, Tid uint32
	Addr     uint64
	Len      uint64
	Pgoff    uint64

	// union: build-id flavour
	HasBuildID  bool
	BuildIDSize uint8
	BuildID     [20]byte // padded to 20 bytes; SHA-1 build-ids are exactly that

	Prot     uint32
	Flags    uint32
	Filename string
}

Mmap2Record is the in-memory image of a PERF_RECORD_MMAP2 payload. Set HasBuildID when emitting the build-id flavour of the union; otherwise the maj/min/ino path is used (and all four fields stay zero).

type SampleRecord

type SampleRecord struct {
	IP        uint64   // PERF_SAMPLE_IP
	Pid, Tid  uint32   // PERF_SAMPLE_TID
	Time      uint64   // PERF_SAMPLE_TIME (ns since clock origin)
	Cpu       uint32   // PERF_SAMPLE_CPU (low 32 bits)
	Period    uint64   // PERF_SAMPLE_PERIOD
	UserIPs   []uint64 // PERF_SAMPLE_CALLCHAIN — user-space IPs (leaf first)
	KernelIPs []uint64 // kernel-space IPs (leaf first); emitted before UserIPs with PERF_CONTEXT markers
}

SampleRecord is the in-memory image of a PERF_RECORD_SAMPLE payload, for the fixed sample_type we emit:

IP | TID | TIME | CPU | PERIOD | CALLCHAIN

(No ADDR, ID, STREAM_ID, READ, RAW, BRANCH_STACK, REGS_USER, STACK_USER, WEIGHT, DATA_SRC, TRANSACTION.)

type Writer

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

Writer writes a perf.data file in the kernel's standard format. Methods AddComm, AddMmap2, AddSample, AddFinishedRound, AddBuildID are append-only and not concurrency-safe — callers (perf-agent's CPU profiler) call them from a single goroutine. Close finalizes the file (writes feature sections, patches header offsets/sizes).

If any append fails (e.g. ENOSPC), the first error is latched and subsequent Add* calls become no-ops; Close returns the latched error. This keeps pos in sync with bytes actually written and prevents the finalizer from patching the header with offsets that point past the real end of the data section.

func Open

func Open(path string, spec EventSpec, meta MetaInfo) (*Writer, error)

Open creates a new perf.data file at path and writes the file header, attr section, and attr_id table. The data section starts immediately after, and Add* calls append records into it. Close patches header offsets/sizes and emits feature sections.

func (*Writer) AddBuildID

func (w *Writer) AddBuildID(e BuildIDEntry)

AddBuildID records a binary's build-id for emission in the HEADER_BUILD_ID feature section at Close.

func (*Writer) AddComm

func (w *Writer) AddComm(r CommRecord)

AddComm appends a PERF_RECORD_COMM record.

func (*Writer) AddFinishedRound

func (w *Writer) AddFinishedRound()

AddFinishedRound appends a PERF_RECORD_FINISHED_ROUND marker.

func (*Writer) AddKernelMmap

func (w *Writer) AddKernelMmap() error

AddKernelMmap emits PERF_RECORD_MMAP2 for [kernel.kallsyms]_text so `perf report` resolves kernel symbols against /proc/kallsyms (or its own kallsyms snapshot). Should be called once at writer init, before any sample records. pid=-1 (kernel-or-any), tid=0.

Address range: when /proc/kallsyms is readable, uses the real (_text, _etext-_text) extent. When unreadable / kptr-restricted, uses the conventional x86_64/arm64 kernel base + a catch-all length so module text outside _text..(_etext) is still attributed to this MMAP2. `perf report` falls back to its own /proc/kallsyms snapshot for symbol resolution in either case.

func (*Writer) AddMmap2

func (w *Writer) AddMmap2(r Mmap2Record)

AddMmap2 appends a PERF_RECORD_MMAP2 record.

func (*Writer) AddSample

func (w *Writer) AddSample(r SampleRecord)

AddSample appends a PERF_RECORD_SAMPLE record.

func (*Writer) Close

func (w *Writer) Close() error

Close finalizes the file: emits feature sections, builds the feature index table, patches the file header's offsets/sizes/feature bitmap, and closes the underlying file. If any earlier Add* call hit a write error, Close returns that latched error after attempting to close the file; the on-disk output is then not a valid perf.data and the caller should delete it.