perffile

package
v0.0.0-...-7b712e5 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Mar 3, 2023 License: BSD-3-Clause Imports: 9 Imported by: 2

Documentation

Overview

Package perffile is a parser for Linux perf.data profiles.

Parsing a perf.data profile starts with a call to New or Open to open a perf.data file. A perf.data file consists of a sequence of records, which can be retrieved with File.Records, as well as several metadata fields, which can be retrieved with other methods of File.

Example 
f, err := Open("perf.data")
if err != nil {
	log.Fatal(err)
}
defer f.Close()

rs := f.Records(RecordsTimeOrder)
for rs.Next() {
	switch r := rs.Record.(type) {
	case *RecordSample:
		fmt.Printf("sample: %+v\n", r)
	}
}
if err := rs.Err(); err != nil {
	log.Fatal(err)
}

Output:

Index

Examples

Constants

View Source 
const (
	BreakpointOpR  BreakpointOp = 1
	BreakpointOpW               = 2
	BreakpointOpRW              = BreakpointOpR | BreakpointOpW
	BreakpointOpX               = 4
)
View Source 
const (
	CallchainHV          uint64 = 0xffffffffffffffe0 // -32
	CallchainKernel             = 0xffffffffffffff80 // -128
	CallchainUser               = 0xfffffffffffffe00 // -512
	CallchainGuest              = 0xfffffffffffff800 // -2048
	CallchainGuestKernel        = 0xfffffffffffff780 // -2176
	CallchainGuestUser          = 0xfffffffffffff600 // -2560
)

Special markers used in RecordSample.Callchain to mark boundaries between types of stacks.

These correspond to PERF_CONTEXT_* from include/uapi/linux/perf_event.h

Variables

This section is empty.

Functions

This section is empty.

Types

type AuxFlags 

type AuxFlags uint64

AuxFlags gives flags for an RecordAux event. 

const (
	// Record was truncated to fit in the ring buffer.
	AuxFlagTruncated AuxFlags = 1 << iota

	// AUX data was collected in overwrite mode, so the AUX buffer
	// was treated as a circular ring buffer.
	AuxFlagOverwrite

	// Record contains gaps.
	AuxFlagPartial

	// Sample collided with another.
	AuxFlagCollision
)

func (AuxFlags) String 

func (i AuxFlags) String() string

type AuxPMUFormat 

type AuxPMUFormat uint8

AuxPMUFormat is the PMU specific trace format type. Values are architecture dependent. 

const (
	// ARM
	AuxPMUFormatCoresightCoresight AuxPMUFormat = 0 // ARM Coresight format CORESIGHT.
	AuxPMUFormatCoresightRaw       AuxPMUFormat = 1 // ARM Coresight format RAW.

	AuxPMUFormatDefault AuxPMUFormat = 0
)

func (AuxPMUFormat) String 

func (i AuxPMUFormat) String() string

type BPFEventFlags 

type BPFEventFlags uint16

type BPFEventType 

type BPFEventType uint16
const (
	BPFEventTypeUnknown BPFEventType = iota
	BPFEventTypeProgLoad
	BPFEventTypeProgUnload
)

func (BPFEventType) String 

func (i BPFEventType) String() string

type BranchFlags 

type BranchFlags uint64
const (
	// BranchFlagMispredicted indicates branch target was mispredicted.
	BranchFlagMispredicted BranchFlags = 1 << iota

	// BranchFlagPredicted indicates branch target was predicted.
	// In case predicted/mispredicted information is unavailable,
	// both flags will be unset.
	BranchFlagPredicted

	// BranchFlagInTransaction indicates the branch occurred in a
	// transaction.
	BranchFlagInTransaction

	// BranchFlagAbort indicates the branch is a transaction abort.
	BranchFlagAbort
)

func (BranchFlags) String 

func (i BranchFlags) String() string

type BranchRecord 

type BranchRecord struct {
	From, To uint64
	Flags    BranchFlags

	Cycles uint16 // Cycle count to last branch (or 0)

	// Type is the type of branch instruction that caused this
	// branch. If supported, this is set by the kernel by
	// disassembling the branch instruction, since the binary
	// itself may not be available at decoding time. This is only
	// set if EventAttr.BranchSampleType&BranchSampleTypeSave is
	// set in the event.
	Type BranchType
}

A BranchRecord records a single branching event in a sample.

type BranchSampleType 

type BranchSampleType uint64

BranchSampleType is a bit-field of the types of branches to record in the branch stack.

This can include privilege levels to record, which can be different from the privilege levels of the event being sampled. If none of the privilege level bits are set, it defaults to the privilege levels of the event.

This corresponds to the perf_branch_sample_type enum from include/uapi/linux/perf_event.h 

const (
	BranchSampleUser   BranchSampleType = 1 << iota // User branches
	BranchSampleKernel                              // Kernel branches
	BranchSampleHV                                  // Hypervisor branches

	BranchSampleAny       // Any branch types
	BranchSampleAnyCall   // Any call branch
	BranchSampleAnyReturn // Any return branch
	BranchSampleIndCall   // Indirect calls
	BranchSampleAbortTX   // Transaction aborts
	BranchSampleInTX      // In transaction
	BranchSampleNoTX      // Not in transaction
	BranchSampleCond      // Conditional branches

	BranchSampleCallStack // Call/ret stack
	BranchSampleIndJump   // Indirect jumps
	BranchSampleCall      // Direct call

	BranchSampleNoFlags  // Don't set BranchRecord.Flags
	BranchSampleNoCycles // Don't set BranchRecord.Cycles
	BranchSampleTypeSave // Do set BranchRecord.Type
	BranchSampleHWIndex  // Do set RecordSample.BranchHWIndex
)

func (BranchSampleType) String 

func (i BranchSampleType) String() string

type BranchType 

type BranchType uint8
const (
	BranchTypeUnknown  BranchType = iota // unknown
	BranchTypeCond                       // conditional
	BranchTypeUncond                     // unconditional
	BranchTypeInd                        // indirect
	BranchTypeCall                       // function call
	BranchTypeIndCall                    // indirect function call
	BranchTypeRet                        // function return
	BranchTypeSyscall                    // syscall
	BranchTypeSysret                     // syscall return
	BranchTypeCondCall                   // conditional function call
	BranchTypeCondRet                    // conditional function return
	BranchTypeEret                       // exception return
	BranchTypeIrq                        // interrupt
)

type BreakpointOp 

type BreakpointOp uint32

BreakpointOp is a type of memory access that can trigger a breakpoint event.

This corresponds to the HW_BREAKPOINT_* constants from include/uapi/linux/hw_breakpoint.h

func (BreakpointOp) String 

func (i BreakpointOp) String() string

type BuildID 

type BuildID []byte

func (BuildID) String 

func (b BuildID) String() string

type BuildIDInfo 

type BuildIDInfo struct {
	CPUMode  CPUMode
	PID      int // Usually -1; for VM kernels
	BuildID  BuildID
	Filename string
}

A BuildIDInfo records the mapping between a single build ID and the path of an executable with that build ID.

type CPUMode 

type CPUMode uint16

A CPUMode indicates the privilege level of a sample or event.

This corresponds to PERF_RECORD_MISC_CPUMODE from include/uapi/linux/perf_event.h 

const (
	CPUModeUnknown CPUMode = iota
	CPUModeKernel
	CPUModeUser
	CPUModeHypervisor
	CPUModeGuestKernel
	CPUModeGuestUser
)

func (CPUMode) String 

func (i CPUMode) String() string

type CPUSet 

type CPUSet []int

A CPUSet represents a set of CPUs by CPU index.

func (CPUSet) String 

func (c CPUSet) String() string

type Count 

type Count struct {
	Value       uint64     // Event counter value
	TimeEnabled uint64     // if ReadFormatTotalTimeEnabled
	TimeRunning uint64     // if ReadFormatTotalTimeRunning
	EventAttr   *EventAttr // if ReadFormatID
}

A Count records the raw value of an event counter.

Typically only a subset of the fields are used. Which fields are set can be determined from the bitmask in the sample's EventAttr.ReadFormat.

This corresponds to perf_event_read_format from include/uapi/linux/perf_event.h

type DataSrc 

type DataSrc struct {
	Op       DataSrcOp
	Miss     bool // if true, Level specifies miss, rather than hit
	Level    DataSrcLevel
	Snoop    DataSrcSnoop
	Locked   DataSrcLock
	TLB      DataSrcTLB
	LevelNum DataSrcLevelNum
	Remote   bool
	Block    DataSrcBlock
	Hops     DataSrcHops
}

type DataSrcBlock 

type DataSrcBlock int
const (
	DataSrcBlockData DataSrcBlock = 1 << iota // Data could not be forwarded
	DataSrcBlockAddr                          // Address conflict

	DataSrcBlockNA DataSrcBlock = 0
)

func (DataSrcBlock) String 

func (i DataSrcBlock) String() string

type DataSrcHops 

type DataSrcHops int
const (
	DataSrcHopsCore   DataSrcHops = 1 // Remote core, same node
	DataSrcHopsNode   DataSrcHops = 3 // Remote node, same socket
	DataSrcHopsSocket DataSrcHops = 3 // Remote socket, same board
	DataSrcHopesBoard DataSrcHops = 4 // Remote board

	DataSrcHopsNA DataSrcHops = 0
)

func (DataSrcHops) String 

func (i DataSrcHops) String() string

type DataSrcLevel 

type DataSrcLevel int
const (
	DataSrcLevelL1  DataSrcLevel = 1 << iota
	DataSrcLevelLFB              // Line fill buffer
	DataSrcLevelL2
	DataSrcLevelL3
	DataSrcLevelLocalRAM     // Local DRAM
	DataSrcLevelRemoteRAM1   // Remote DRAM (1 hop)
	DataSrcLevelRemoteRAM2   // Remote DRAM (2 hops)
	DataSrcLevelRemoteCache1 // Remote cache (1 hop)
	DataSrcLevelRemoteCache2 // Remote cache (2 hops)
	DataSrcLevelIO           // I/O memory
	DataSrcLevelUncached

	DataSrcLevelNA DataSrcLevel = 0
)

func (DataSrcLevel) String 

func (i DataSrcLevel) String() string

type DataSrcLevelNum 

type DataSrcLevelNum int
const (
	DataSrcLevelNumL1       DataSrcLevelNum = 0x01 // L1
	DataSrcLevelNumL2       DataSrcLevelNum = 0x02 // L2
	DataSrcLevelNumL3       DataSrcLevelNum = 0x03 // L3
	DataSrcLevelNumL4       DataSrcLevelNum = 0x04 // L4
	DataSrcLevelNumAnyCache DataSrcLevelNum = 0x0b // Any cache
	DataSrcLevelNumLFB      DataSrcLevelNum = 0x0c // LFB
	DataSrcLevelNumRAM      DataSrcLevelNum = 0x0d // RAM
	DataSrcLevelNumPMEM     DataSrcLevelNum = 0x0e // PMEM
	DataSrcLevelNumNA       DataSrcLevelNum = 0x0f // N/A
)

func (DataSrcLevelNum) String 

func (i DataSrcLevelNum) String() string

type DataSrcLock 

type DataSrcLock int
const (
	DataSrcLockNA DataSrcLock = iota
	DataSrcLockUnlocked
	DataSrcLockLocked
)

func (DataSrcLock) String 

func (i DataSrcLock) String() string

type DataSrcOp 

type DataSrcOp int
const (
	DataSrcOpLoad DataSrcOp = 1 << iota
	DataSrcOpStore
	DataSrcOpPrefetch
	DataSrcOpExec

	DataSrcOpNA DataSrcOp = 0
)

func (DataSrcOp) String 

func (i DataSrcOp) String() string

type DataSrcSnoop 

type DataSrcSnoop int
const (
	DataSrcSnoopNone DataSrcSnoop = 1 << iota
	DataSrcSnoopHit
	DataSrcSnoopMiss
	DataSrcSnoopHitM // Snoop hit modified
	DataSrcSnoopFwd

	DataSrcSnoopNA DataSrcSnoop = 0
)

func (DataSrcSnoop) String 

func (i DataSrcSnoop) String() string

type DataSrcTLB 

type DataSrcTLB int
const (
	DataSrcTLBHit DataSrcTLB = 1 << iota
	DataSrcTLBMiss
	DataSrcTLBL1
	DataSrcTLBL2
	DataSrcTLBHardwareWalker
	DataSrcTLBOSFaultHandler

	DataSrcTLBNA DataSrcTLB = 0
)

func (DataSrcTLB) String 

func (i DataSrcTLB) String() string

type Event 

type Event interface {
	// Generic returns the generic representation of this Event.
	Generic() EventGeneric
}

Event describes a specific performance monitoring event.

Events are quite general. They can be hardware events such as cycles or cache misses. They can be kernel software events such as page faults. They can be user or kernel trace-points, or many other things. All events happen at some instant and can be counted.

type EventAttr 

type EventAttr struct {
	// Event describes the event that will be (or was) counted or
	// sampled.
	Event Event

	// SamplePeriod, if non-zero, is the approximate number of
	// events between each sample.
	//
	// For a sampled event, SamplePeriod will be set if
	// Flags&EventFlagsFreq == 0. See also SampleFreq.
	SamplePeriod uint64

	// SampleFreq, if non-zero, is the approximate number of
	// samples to record per second per core. This is approximated
	// by dynamically adjusting the event sampling period (see
	// perf_calculate_period) and thus is not particularly
	// accurate (and even less accurate for events that don't
	// happen at a regular rate). If SampleFormat includes
	// SampleFormatPeriod, each sample includes the number of
	// events until the next sample on the same CPU.
	//
	// For a sampled event, SampleFreq will be set if
	// Flags&EventFlagsFreq != 0. See also SamplePeriod.
	SampleFreq uint64

	// The format of RecordSamples
	SampleFormat SampleFormat

	// The format of SampleRead
	ReadFormat ReadFormat

	Flags EventFlags

	// Precise indicates the precision of instruction pointers
	// recorded by this event.
	Precise EventPrecision

	// WakeupEvents specifies to wake up every WakeupEvents
	// events. Either this or WakeupWatermark will be non-zero,
	// depending on Flags&EventFlagWakeupWatermark.
	WakeupEvents uint32
	// WakeupWatermark specifies to wake up every WakeupWatermark
	// bytes.
	WakeupWatermark uint32

	// BranchSampleType specifies the types of branches to record
	// in the branch stack if SampleFormat&SampleFormatBranchStack
	// is set, as well as what information to record about each
	// branch.
	BranchSampleType BranchSampleType

	// SampleRegsUser is a bitmask of user-space registers
	// captured at each sample in RecordSample.RegsUser. The
	// hardware register corresponding to each bit depends on the
	// register ABI.
	SampleRegsUser uint64

	// Size of user stack to dump on samples
	SampleStackUser uint32

	// SampleRegsIntr is a bitmask of registers captured at each
	// sample in RecordSample.RegsIntr. If Precise ==
	// EventPrecisionArbitrarySkid, these registers are captured
	// at the PMU interrupt. Otherwise, these registers are
	// captured by the hardware when it samples an instruction.
	SampleRegsIntr uint64

	// AuxWatermark is the watermark for the AUX area in bytes at
	// which user space is woken up to collect the AUX area.
	AuxWatermark uint32

	// SampleMaxStack is the maximum number of frame pointers in a
	// callchain. Should be < /proc/sys/kernel/perf_event_max_stack.
	SampleMaxStack uint16
}

EventAttr describes an event and how that event should be recorded.

This corresponds to the perf_event_attr struct from include/uapi/linux/perf_event.h

type EventBreakpoint 

type EventBreakpoint struct {
	// Op specifies what type of access to Addr should trigger
	// this event.
	Op BreakpointOp
	// Addr is the address to watch for operation Op.
	Addr uint64
	// Len is the number of bytes to watch at Addr. What sizes are
	// supported depends on the hardware, but it generally must be
	// a small power of 2.
	Len uint64
}

EventBreakpoint represents a breakpoint event.

Breakpoint events are triggered by a specific type of access to an address in memory.

func (EventBreakpoint) Generic 

func (e EventBreakpoint) Generic() EventGeneric

type EventFlags 

type EventFlags uint64

EventFlags is a bitmask of boolean properties of an event.

This corresponds to the perf_event_attr enum from include/uapi/linux/perf_event.h 

const (
	// Event is disabled by default
	EventFlagDisabled EventFlags = 1 << iota
	// Children inherit this event
	EventFlagInherit
	// Event must always be on the PMU
	EventFlagPinned
	// Event is only group on PMU
	EventFlagExclusive
	// Don't count events in user/kernel/hypervisor/when idle
	EventFlagExcludeUser
	EventFlagExcludeKernel
	EventFlagExcludeHypervisor
	EventFlagExcludeIdle
	// Include mmap data
	EventFlagMmap
	// Include comm data
	EventFlagComm
	// Use frequency, not period
	EventFlagFreq
	// Per task counts
	EventFlagInheritStat
	// Next exec enables this event
	EventFlagEnableOnExec
	// Trace fork/exit
	EventFlagTask
	// WakeupWatermark is set rather than WakeupEvents.
	EventFlagWakeupWatermark

	// Non-exec mmap data
	EventFlagMmapData EventFlags = 1 << (2 + iota)
	// All events have SampleField fields
	EventFlagSampleIDAll
	// Don't count events in host/guest
	EventFlagExcludeHost
	EventFlagExcludeGuest
	// Don't include kernel/user callchains
	EventFlagExcludeCallchainKernel
	EventFlagExcludeCallchainUser
	// Include inode data in mmap events
	EventFlagMmapInodeData
	// Flag comm events that are due to an exec
	EventFlagCommExec
	// Use clock specified by clockid for time fields
	EventFlagClockID
	// Record context switch data. Enables RecordTypeSwitch and
	// RecordTypeSwitchCPUWide events.
	EventFlagContextSwitch
	// Write ring buffer from end to beginning.
	EventFlagWriteBackward
	// Include namespaces data.
	EventFlagNamespaces
	// Include ksymbol events.
	EventFlagKsymbol
	// Generate aux records instead of events.
	EventFlagAuxOutput
	// Include cgroup events.
	EventFlagCGroup
	// Include text poke events.
	EventFlagTextPoke
	// Use build ID in mmap2 events instead of inode.
	EventFlagBuildID
	// Children only inherit if cloned with CLONE_THREAD.
	EventFlagInheritThread
	// Event is removed from task on exec.
	EventFlagRemoveOnExec
	// Send synchronous SIGTRAP on event.
	EventFlagSigtrap
)

func (EventFlags) String 

func (i EventFlags) String() string

type EventGeneric 

type EventGeneric struct {
	// Type specifies the major type of this event, such as
	// hardware event, software event, or tracepoint.
	Type EventType

	// ID is the specific event within the class described by
	// Type.
	//
	// In perf_event_attr, this corresponds to either
	// perf_event_attr.config or, if Type == EventTypeBreakpoint,
	// perf_event_attr.bp_type.
	ID uint64

	// Config gives additional configuration specific to the event
	// described by Type and ID.
	//
	// In perf_event_attr, this corresponds to
	// perf_event_attr.config1 and config2.
	Config []uint64
}

EventGeneric is a generic representation of a performance event.

Any perf event can be represented by EventGeneric, but some encoding is generally necessary. Hence, EventGeneric can be translated back and forth between specific Event* types.

func (*EventGeneric) Decode 

func (g *EventGeneric) Decode() Event

Decode decodes a generic event g into a specific event type.

type EventHWCache 

type EventHWCache struct {
	Level     HWCache
	Op        HWCacheOp
	Result    HWCacheResult
	PMUTypeID uint32
}

EventHWCache represents a hardware cache event.

func (EventHWCache) Generic 

func (e EventHWCache) Generic() EventGeneric

type EventHardware 

type EventHardware struct {
	ID        EventHardwareID
	PMUTypeID PMUTypeID // Map back to name with FileMeta.PMUMappings
}

EventHardware represents a hardware event.

func (EventHardware) Generic 

func (e EventHardware) Generic() EventGeneric

type EventHardwareID 

type EventHardwareID uint8

EventHardwareID represents a hardware event type.

This corresponds to the perf_hw_id enum from include/uapi/linux/perf_event.h 

const (
	EventHardwareIDCPUCycles EventHardwareID = iota
	EventHardwareIDInstructions
	EventHardwareIDCacheReferences
	EventHardwareIDCacheMisses
	EventHardwareIDBranchInstructions
	EventHardwareIDBranchMisses
	EventHardwareIDBusCycles
	EventHardwareIDStalledCyclesFrontend
	EventHardwareIDStalledCyclesBackend
	EventHardwareIDRefCPUCycles
)

func (EventHardwareID) String 

func (i EventHardwareID) String() string

type EventID 

type EventID uint64

An EventID combined with an EventType describes a specific event.

type EventPrecision 

type EventPrecision int

An EventPrecision indicates the precision of instruction pointers recorded by an event. This can vary depending on the exact method used to capture IPs. 

const (
	EventPrecisionArbitrarySkid EventPrecision = iota
	EventPrecisionConstantSkid
	EventPrecisionTryZeroSkid
	EventPrecisionZeroSkip
)

func (EventPrecision) String 

func (i EventPrecision) String() string

type EventRaw 

type EventRaw uint64

EventRaw represents a "raw" hardware PMU event in a CPU-specific format.

func (EventRaw) Generic 

func (e EventRaw) Generic() EventGeneric

type EventSoftware 

type EventSoftware uint64

EventSoftware represents a software event.

This corresponds to the perf_sw_ids enum from include/uapi/linux/perf_event.h 

const (
	EventSoftwareCPUClock EventSoftware = iota
	EventSoftwareTaskClock
	EventSoftwarePageFaults
	EventSoftwareContextSwitches
	EventSoftwareCPUMigrations
	EventSoftwarePageFaultsMin
	EventSoftwarePageFaultsMaj
	EventSoftwareAlignmentFaults
	EventSoftwareEmulationFaults
	EventSoftwareDummy
	EventSoftwareBpfOutput
	EventSoftwareCGroupSwitches
)

func (EventSoftware) Generic 

func (e EventSoftware) Generic() EventGeneric

func (EventSoftware) String 

func (i EventSoftware) String() string

type EventTracepoint 

type EventTracepoint uint64

EventTracepoint represents a kernel tracepoint event.

The IDs of the tracepoint events are given by the tracing/events/*/*/id files under debugfs.

func (EventTracepoint) Generic 

func (e EventTracepoint) Generic() EventGeneric

type EventType 

type EventType uint32

An EventType is a general class of performance event.

This corresponds to the perf_type_id enum from include/uapi/linux/perf_event.h 

const (
	EventTypeHardware EventType = iota
	EventTypeSoftware
	EventTypeTracepoint
	EventTypeHWCache
	EventTypeRaw
	EventTypeBreakpoint
)

func (EventType) String 

func (i EventType) String() string

type File 

type File struct {
	// Meta contains the metadata for this profile, such as
	// information about the hardware.
	Meta FileMeta

	// Events lists all events that may appear in this profile.
	Events []*EventAttr
	// contains filtered or unexported fields
}

A File is a perf.data file. It consists of a sequence of records, which can be retrieved with the Records method, as well as several optional metadata fields.

func New 

func New(r io.ReaderAt) (*File, error)

New reads a "perf.data" file from r.

The caller must keep r open as long as it is using the returned *File.

func Open 

func Open(name string) (*File, error)

Open opens the named "perf.data" file using os.Open.

The caller must call f.Close() on the returned file when it is done.

func (*File) Close 

func (f *File) Close() error

Close closes the File.

If the File was created using New directly instead of Open, Close has no effect.

func (*File) Records 

func (f *File) Records(order RecordsOrder) *Records

Records returns an iterator over the records in the profile. The order argument specifies the order for iterating through the records in this File. Callers should choose the least resource-intensive iteration order that satisfies their needs.

type FileMeta 

type FileMeta struct {
	// BuildIDs is the list of build IDs for processes and
	// libraries in this profile, or nil if unknown. Note that in
	// "live mode" (e.g., a file written by perf inject), it's
	// possible for build IDs to be introduced in the sample
	// stream itself.
	BuildIDs []BuildIDInfo

	// Hostname is the hostname of the machine that recorded this
	// profile, or "" if unknown.
	Hostname string

	// OSRelease is the OS release of the machine that recorded
	// this profile such as "3.13.0-62", or "" if unknown.
	OSRelease string

	// Version is the perf version that recorded this profile such
	// as "3.13.11", or "" if unknown.
	Version string

	// Arch is the host architecture of the machine that recorded
	// this profile such as "x86_64", or "" if unknown.
	Arch string

	// CPUsOnline and CPUsAvail are the number of online and
	// available CPUs of the machine that recorded this profile,
	// or 0, 0 if unknown.
	CPUsOnline, CPUsAvail int

	// CPUDesc describes the CPU of the machine that recorded this
	// profile such as "Intel(R) Core(TM) i7-4600U CPU @ 2.10GHz",
	// or "" if unknown.
	CPUDesc string

	// CPUID describes the CPU type of the machine that recorded
	// this profile, or "" if unknown. The exact format of this
	// varies between architectures. On x86 architectures, it is a
	// comma-separated list of vendor, family, model, and
	// stepping, such as "GenuineIntel,6,69,1".
	CPUID string

	// TotalMem is the total memory in bytes of the machine that
	// recorded this profile, or 0 if unknown.
	TotalMem int64

	// CmdLine is the list of command line arguments perf was
	// invoked with, or nil if unknown.
	CmdLine []string

	// CoreGroups and ThreadGroups describe the CPU topology of
	// the machine that recorded this profile. Each CPUSet in
	// CoreGroups is a set of CPUs in the same package, and each
	// CPUSet in ThreadGroups is a set of hardware threads in the
	// same core. These will be nil if unkneon.
	CoreGroups, ThreadGroups []CPUSet

	// NUMANodes is the set of NUMA nodes in the NUMA topology of
	// the machine that recorded this profile, or nil if unknown.
	NUMANodes []NUMANode

	// PMUMappings is a map from numerical PMUTypeID to name for
	// event classes supported by the machine that recorded this
	// profile, or nil if unknown.
	PMUMappings map[PMUTypeID]string

	// Groups is the descriptions of each perf event group in this
	// profile, or nil if unknown.
	Groups []GroupDesc
}

type GroupDesc 

type GroupDesc struct {
	Name       string
	Leader     int
	NumMembers int
}

A GroupDesc describes a group of PMU events that are scheduled together.

TODO: Are Leader and NumMembers attribute IDs? If so, we should probably map them to *EventAttrs to make this useful.

type HWCache 

type HWCache uint8

HWCache represents a level in the hardware cache.

This corresponds to the perf_hw_cache_id enum from include/uapi/linux/perf_event.h 

const (
	HWCacheL1D HWCache = iota
	HWCacheL1I
	HWCacheLL
	HWCacheDTLB
	HWCacheITLB
	HWCacheBPU
	HWCacheNode
)

func (HWCache) String 

func (i HWCache) String() string

type HWCacheOp 

type HWCacheOp uint8

HWCacheOp represents a type of access to a hardware cache.

This corresponds to the perf_hw_cache_op_id enum from include/uapi/linux/perf_event.h 

const (
	HWCacheOpRead HWCacheOp = iota
	HWCacheOpWrite
	HWCacheOpPrefetch
)

func (HWCacheOp) String 

func (i HWCacheOp) String() string

type HWCacheResult 

type HWCacheResult uint8

HWCacheResult represents the result of a accessing a hardware cache.

This corresponds to the perf_hw_cache_op_result_id enum from include/uapi/linux/perf_event.h 

const (
	HWCacheResultAccess HWCacheResult = iota
	HWCacheResultMiss
)

func (HWCacheResult) String 

func (i HWCacheResult) String() string

type KsymbolFlags 

type KsymbolFlags uint64

KsymbolFlags gives flags for a RecordKsymbol event. 

const (
	// Ksymbol was unregistered.
	KsymbolFlagUnregister KsymbolFlags = iota
)

func (KsymbolFlags) String 

func (i KsymbolFlags) String() string

type KsymbolType 

type KsymbolType uint16
const (
	KsymbolTypeUnknown KsymbolType = iota
	KsymbolTypeBpf
	KsymbolTypeOol
)

func (KsymbolType) String 

func (i KsymbolType) String() string

type NUMANode 

type NUMANode struct {
	// Node is the system identifier of this NUMA node.
	Node int

	// MemTotal and MemFree are the total and free number of bytes
	// of memory in this NUMA node.
	MemTotal, MemFree int64

	// CPUs is the set of CPUs in this NUMA node.
	CPUs CPUSet
}

A NUMANode represents a single hardware NUMA node.

type Namespace 

type Namespace struct {
	Dev, Inode uint64
}

type PMUTypeID 

type PMUTypeID uint32

PMUTypeID is a kernel-assigned type id assigned on PMU registration, visible at /sys/bus/event_source/devices/$PMU/type.

type ReadFormat 

type ReadFormat uint64

ReadFormat is a bitmask of the fields recorded in the SampleRead field(s) of a sample.

This corresponds to the perf_event_read_format enum from include/uapi/linux/perf_event.h 

const (
	ReadFormatTotalTimeEnabled ReadFormat = 1 << iota
	ReadFormatTotalTimeRunning
	ReadFormatID
	ReadFormatGroup
)

func (ReadFormat) String 

func (i ReadFormat) String() string

type Record 

type Record interface {
	Type() RecordType
	Common() *RecordCommon
}

Record is the common interface implemented by all profile record types.

type RecordAux 

type RecordAux struct {
	RecordCommon

	Offset, Size uint64
	Flags        AuxFlags
	PMUFormat    AuxPMUFormat
}

A RecordAux records the data was added to the AUX buffer.

func (*RecordAux) Type 

func (r *RecordAux) Type() RecordType

type RecordAuxOutputHardwareID 

type RecordAuxOutputHardwareID struct {
	RecordCommon

	ID uint64
}

RecordAuxOutputHardwareID records an archtecture-specific hardware ID assosciated with the aux data for this event ID.

e.g., this is used to disambiguate different PEBS event types from each other when using PEBS-via-PT.

func (*RecordAuxOutputHardwareID) Type 

func (r *RecordAuxOutputHardwareID) Type() RecordType

type RecordAuxtrace 

type RecordAuxtrace struct {
	// TID and CPU are always filled in.
	RecordCommon

	// Offset is the byte offset of the aux data in the aux mmap.
	// Not meaningful in perf data files.
	Offset uint64

	// Ref is a unique identifier for this auxtrace block.
	//
	// TODO: What's the point of this? Is it cross-referenced
	// against something?
	Ref uint64

	// Idx is the index of the aux mmap region of this data.
	// Not meaningful in perf data files.
	Idx uint32

	// Data is the raw auxiliary data. The encoding of this
	// depends on the latest RecordAuxtraceInfo.
	Data []byte
}

func (*RecordAuxtrace) Type 

func (r *RecordAuxtrace) Type() RecordType

type RecordAuxtraceInfo 

type RecordAuxtraceInfo struct {
	RecordCommon

	Kind uint32

	Priv []uint64
}

func (*RecordAuxtraceInfo) Type 

func (r *RecordAuxtraceInfo) Type() RecordType

type RecordBPFEvent 

type RecordBPFEvent struct {
	RecordCommon

	EventType BPFEventType
	Flags     BPFEventFlags
	ID        uint32
	Tag       uint64
}

RecordBPFEvent records BPF program load/unload information.

func (*RecordBPFEvent) Type 

func (r *RecordBPFEvent) Type() RecordType

type RecordCGroup 

type RecordCGroup struct {
	RecordCommon

	ID   uint32
	Path string
}

RecordCGroup records the assosciation between a cgroup id and path.

func (*RecordCGroup) Type 

func (r *RecordCGroup) Type() RecordType

type RecordComm 

type RecordComm struct {
	// RecordCommon.PID and .TID will always be filled
	RecordCommon

	Exec bool // from header.misc

	Comm string
}

A RecordComm records that a process being profiled called exec. RecordComms can also occur at the beginning of a profile to describe the existing set of processes.

func (*RecordComm) Type 

func (r *RecordComm) Type() RecordType

type RecordCommon 

type RecordCommon struct {
	// Offset is the byte offset of this event in the perf.data
	// file.
	Offset int64

	// Format is a bit mask of SampleFormat* values that indicate
	// which optional fields of this record are valid.
	Format SampleFormat

	// EventAttr is the event, if any, associated with this record.
	EventAttr *EventAttr

	PID, TID int    // if SampleFormatTID
	Time     uint64 // if SampleFormatTime
	ID       attrID // if SampleFormatID or SampleFormatIdentifier
	StreamID uint64 // if SampleFormatStreamID
	CPU, Res uint32 // if SampleFormatCPU
}

RecordCommon stores fields that are common to all record types, as well as additional metadata. It is not itself a Record.

Many fields are optional and their presence is determined by the bitmask EventAttr.SampleFormat. Some record types guarantee that some of these fields will be filled.

func (*RecordCommon) Common 

func (r *RecordCommon) Common() *RecordCommon

type RecordExit 

type RecordExit struct {
	// RecordCommon.PID, .TID, and .Time will always be filled
	RecordCommon

	PPID, PTID int
}

A RecordExit records that a process or thread exited.

func (*RecordExit) Type 

func (r *RecordExit) Type() RecordType

type RecordFork 

type RecordFork struct {
	// RecordCommon.PID, .TID, and .Time will always be filled
	RecordCommon

	PPID, PTID int
}

A RecordFork records that a process called clone to either fork the process or create a new thread.

func (*RecordFork) Type 

func (r *RecordFork) Type() RecordType

type RecordItraceStart 

type RecordItraceStart struct {
	// PID and TID will always be filled in.
	RecordCommon
}

A RecordItraceStart indicates that an instruction trace started.

func (*RecordItraceStart) Type 

func (r *RecordItraceStart) Type() RecordType

type RecordKsymbol 

type RecordKsymbol struct {
	RecordCommon

	Addr     uint64
	Len      uint32
	KsymType KsymbolType
	Flags    KsymbolFlags
	Name     string
}

RecordKsymbol record kernel symbol register/unregister information, for dynamically loaded or JITed kernel functions.

func (*RecordKsymbol) Type 

func (r *RecordKsymbol) Type() RecordType

type RecordLost 

type RecordLost struct {
	// RecordCommon.ID and .EventAttr will always be filled
	RecordCommon

	NumLost uint64
}

A RecordLost records that profiling events were lost because of a buffer overflow.

func (*RecordLost) Type 

func (r *RecordLost) Type() RecordType

type RecordLostSamples 

type RecordLostSamples struct {
	RecordCommon

	Lost uint64
}

A RecordLostSamples records the number of dropped or lost samples.

func (*RecordLostSamples) Type 

func (r *RecordLostSamples) Type() RecordType

type RecordMmap 

type RecordMmap struct {
	// RecordCommon.PID and .TID will always be filled
	RecordCommon

	Data bool // from header.misc

	// Addr and Len are the virtual address of the start of this
	// mapping and its length in bytes.
	Addr, Len uint64
	// FileOffset is the byte offset in the mapped file of the
	// beginning of this mapping.
	FileOffset uint64

	Major, Minor       uint32 // if !EventFlagBuildID
	Ino, InoGeneration uint64 // if !EventFlagBuildID

	BuildID []byte // if EventFlagBuildID

	Prot, Flags uint32
	Filename    string
}

A RecordMmap records when a process being profiled called mmap. RecordMmaps can also occur at the beginning of a profile to describe the existing memory layout.

func (*RecordMmap) Type 

func (r *RecordMmap) Type() RecordType

type RecordNamespaces 

type RecordNamespaces struct {
	// PID and TID are always filled in.
	RecordCommon

	Namespaces []Namespace
}

func (*RecordNamespaces) Type 

func (r *RecordNamespaces) Type() RecordType

type RecordSample 

type RecordSample struct {
	// RecordCommon.EventAttr will always be filled.
	// RecordCommon.Format descibes the optional fields in this
	// structure, as well as the optional common fields.
	RecordCommon

	CPUMode CPUMode // from header.misc
	ExactIP bool    // from header.misc

	IP   uint64 // if SampleFormatIP
	Addr uint64 // if SampleFormatAddr

	// Period is the number of events on this CPU until the next
	// sample. In frequency sampling mode, this is adjusted
	// dynamically based on the rate of recent events. In period
	// sampling mode, this is fixed.
	Period uint64 // if SampleFormatPeriod

	// SampleRead records raw event counter values. If this is an
	// event group, this slice will have more than one element;
	// otherwise, it will have one element.
	SampleRead []Count // if SampleFormatRead

	// Callchain gives the call stack of the sampled instruction,
	// starting from the sampled instruction itself. The call
	// chain may span several types of stacks (e.g., it may start
	// in a kernel stack, then transition to a user stack). Before
	// the first IP from each stack there will be a Callchain*
	// constant indicating the stack type for the following IPs.
	Callchain []uint64 // if SampleFormatCallchain

	// BranchHWIndex is the low level index of the raw hardware branch
	// record (e.g., LBR) for BranchStack[0].
	//
	// BranchStack is an abstraction of the raw hardware branch records,
	// and the index of the raw entry can be very useful for stitching the
	// stacks of multiple samples to reconstruct the call stack.
	//
	// The value is between -1 (unknown) and the max depth from
	// /sys/devices/cpu/caps/branches.
	BranchHWIndex int64 // if BranchSampleHWIndex

	BranchStack []BranchRecord // if SampleFormatBranchStack

	// RegsUserABI and RegsUser record the ABI and values of
	// user-space registers as of this sample. Note that these are
	// the current user-space registers even if this sample
	// occurred at a kernel PC. RegsUser[i] records the value of
	// the register indicated by the i-th set bit of
	// EventAttr.SampleRegsUser.
	RegsUserABI SampleRegsABI // if SampleFormatRegsUser
	RegsUser    []uint64      // if SampleFormatRegsUser

	// RegsIntrABI And RegsIntr record the ABI and values of
	// registers as of this sample. Unlike RegsUser, these can be
	// kernel-space registers if this sample occurs in the kernel.
	// RegsIntr[i] records the value of the register indicated by
	// the i-th set bit of EventAttr.SampleRegsIntr.
	RegsIntrABI SampleRegsABI // if SampleFormatRegsIntr
	RegsIntr    []uint64      // if SampleFormatRegsIntr

	StackUser        []byte // if SampleFormatStackUser
	StackUserDynSize uint64 // if SampleFormatStackUser

	Weight  uint64  // if SampleFormatWeight or SampleFormatWeightStruct
	Weights Weights // if SampleFormatWeightStruct

	DataSrc DataSrc // if SampleFormatDataSrc

	Transaction Transaction // if SampleFormatTransaction
	AbortCode   uint32      // if SampleFormatTransaction

	PhysAddr uint64 // if SampleFormatPhysAddr

	CGroup uint64 // if SampleFormatCGroup

	DataPageSize uint64 // if SampleFormatDataPageSize
	CodePageSize uint64 // if SampleFormatCodePageSize

	Aux []byte // if SampleFormatAux
}

A RecordSample records a profiling sample event.

Typically only a subset of the fields are used. Which fields are set can be determined from the bitmask RecordSample.EventAttr.SampleFormat.

func (*RecordSample) Fields 

func (r *RecordSample) Fields() []string

Fields returns the list of names of valid fields in r based on r.Format. This is useful for writing custom printing functions.

func (*RecordSample) String 

func (r *RecordSample) String() string

func (*RecordSample) Type 

func (r *RecordSample) Type() RecordType

type RecordSwitch 

type RecordSwitch struct {
	RecordCommon

	// Out indicates this is a switch out. Otherwise, this is a
	// switch in.
	Out bool
}

A RecordSwitch records a context switch in or out of the monitored process. See also RecordSwitchCPUWide.

func (*RecordSwitch) Type 

func (r *RecordSwitch) Type() RecordType

type RecordSwitchCPUWide 

type RecordSwitchCPUWide struct {
	RecordCommon

	// Out indicates this is a switch out. Otherwise, this is a
	// switch in.
	Out bool

	// Preempt indicates that the preempted thread was in
	// TASK_RUNNING state. That is, this was an involuntary
	// preemption.
	Preempt bool

	// SwitchPID and SwitchTID are the PID and TID of the process
	// being switched in or switched out.
	SwitchPID, SwitchTID int
}

RecordSwitchCPUWide is a CPU-wide version of RecordSwitch.

func (*RecordSwitchCPUWide) Type 

func (r *RecordSwitchCPUWide) Type() RecordType

type RecordTextPoke 

type RecordTextPoke struct {
	RecordCommon

	Addr uint64
	Old  []byte
	New  []byte
}

RecordTextPoke records single instruction changes to the kernel text. This event records the address modified and the old and new code.

func (*RecordTextPoke) Type 

func (r *RecordTextPoke) Type() RecordType

type RecordThrottle 

type RecordThrottle struct {
	// RecordCommon.Time, .ID, and .StreamID, and .EventAttr will
	// always be filled
	RecordCommon

	Enable bool
}

A RecordThrottle records that interrupt throttling was enabled or disabled.

func (*RecordThrottle) Type 

func (r *RecordThrottle) Type() RecordType

type RecordType 

type RecordType uint32

A RecordType indicates the type of a record in a profile. A record can either be a profiling sample or give information about changes to system state, such as a process calling mmap. 

const (
	RecordTypeMmap RecordType = 1 + iota
	RecordTypeLost
	RecordTypeComm
	RecordTypeExit
	RecordTypeThrottle
	RecordTypeUnthrottle
	RecordTypeFork
	RecordTypeRead
	RecordTypeSample

	RecordTypeAux
	RecordTypeItraceStart
	RecordTypeLostSamples // TODO: How does this differ from RecordTypeLost?
	RecordTypeSwitch
	RecordTypeSwitchCPUWide
	RecordTypeNamespaces
	RecordTypeKsymbol
	RecordTypeBPFEvent
	RecordTypeCGroup
	RecordTypeTextPoke
	RecordTypeAuxOutputHardwareID
)
const (
	RecordTypeAuxtraceInfo RecordType // TODO
	RecordTypeAuxtrace
	RecordTypeAuxtraceError // TODO

)

perf_user_event_type in tools/perf/util/event.h

TODO: Figure out what to do with these. Some of these are only to direct parsing so they should never escape the API. Some of these are only for perf.data pipes.

func (RecordType) String 

func (i RecordType) String() string

type RecordUnknown 

type RecordUnknown struct {
	RecordCommon

	Data []byte
	// contains filtered or unexported fields
}

A RecordUnknown is a Record of unknown or unimplemented type.

func (*RecordUnknown) Type 

func (r *RecordUnknown) Type() RecordType

type Records 

type Records struct {
	// The current record. The concrete type of this will be one
	// of the Record* types. Determine which type of record this
	// is using a type switch.
	Record Record
	// contains filtered or unexported fields
}

A Records is an iterator over the records in a "perf.data" file. Each record will be one of the Record* types.

Typical usage is 

rs := file.Records()
for rs.Next() {
  switch r := rs.Record.(type) {
  case *perffile.RecordSample:
    ...
  }
}
if rs.Err() { ... }

func (*Records) Err 

func (r *Records) Err() error

Err returns the first error encountered by Records.

func (*Records) Next 

func (r *Records) Next() bool

Next fetches the next record into r.Record. It returns true if successful, and false if it reaches the end of the record stream or encounters an error.

The record stored in r.Record may be reused by later invocations of Next, so if the caller may need the record after another call to Next, it must make its own copy.

type RecordsOrder 

type RecordsOrder int
const (
	// RecordsFileOrder requests records in file order. This is
	// efficient because it allows streaming the records directly
	// from the file, but the records may not be in time-stamp or
	// even causal order.
	RecordsFileOrder RecordsOrder = iota

	// RecordsCausalOrder requests records in causal order. This
	// is weakly time-ordered: any two records will be in
	// time-stamp order *unless* those records are both
	// RecordSamples. This is potentially more efficient than
	// RecordsTimeOrder, though currently the implementation does
	// not distinguish.
	RecordsCausalOrder

	// RecordsTimeOrder requests records in time-stamp order. This
	// is the most expensive iteration order because it requires
	// buffering and/or re-reading potentially large sections of
	// the input file in order to sort the records.
	RecordsTimeOrder
)

func (RecordsOrder) String 

func (i RecordsOrder) String() string

type SampleFormat 

type SampleFormat uint64

A SampleFormat is a bitmask of the fields recorded by a sample.

This corresponds to the perf_event_sample_format enum from include/uapi/linux/perf_event.h 

const (
	SampleFormatIP SampleFormat = 1 << iota
	SampleFormatTID
	SampleFormatTime
	SampleFormatAddr
	SampleFormatRead
	SampleFormatCallchain
	SampleFormatID
	SampleFormatCPU
	SampleFormatPeriod
	SampleFormatStreamID
	SampleFormatRaw
	SampleFormatBranchStack
	SampleFormatRegsUser
	SampleFormatStackUser
	SampleFormatWeight
	SampleFormatDataSrc
	SampleFormatIdentifier
	SampleFormatTransaction
	SampleFormatRegsIntr
	SampleFormatPhysAddr
	SampleFormatAux
	SampleFormatCGroup
	SampleFormatDataPageSize
	SampleFormatCodePageSize
	SampleFormatWeightStruct
)

func (SampleFormat) String 

func (i SampleFormat) String() string

type SampleRegsABI 

type SampleRegsABI uint64

SampleRegsABI indicates the register ABI of a given sample for architectures that support multiple ABIs.

This corresponds to the perf_sample_regs_abi enum from include/uapi/linux/perf_event.h 

const (
	SampleRegsABINone SampleRegsABI = iota
	SampleRegsABI32
	SampleRegsABI64
)

func (SampleRegsABI) String 

func (i SampleRegsABI) String() string

type Transaction 

type Transaction int
const (
	TransactionElision       Transaction = 1 << iota // From elision
	TransactionTransaction                           // From transaction
	TransactionSync                                  // Instruction is related
	TransactionAsync                                 // Instruction is not related
	TransactionRetry                                 // Retry possible
	TransactionConflict                              // Conflict abort
	TransactionCapacityWrite                         // Capactiy write abort
	TransactionCapacityRead                          // Capactiy read abort
)

func (Transaction) String 

func (i Transaction) String() string

type Weights 

type Weights struct {
	Var1 uint32
	Var2 uint16
	Var3 uint16
}

Source Files

View all Source files

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.