perf

package module
v0.0.0-...-30bec95 Latest Latest
Warning

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

 Go to latest Published: Oct 29, 2024 License: BSD-3-Clause Imports: 17 Imported by: 143

README

This is a clone of the golang.org/x/sys/unix/linux/perf submitted by acln0 to review at https://go-review.googlesource.com/c/sys/+/168059

An alternative working tree for this package can also be found at https://github.com/acln0/perf

This Elastic fork contains bugfixes and features necessary for our KProbes implementation.

perf API client package for Linux. See man 2 perf_event_open and include/uapi/linux/perf_event.h.

This package is in its early stages. The API is still under discussion: it may change at any moment, without prior notice. Furthermore, this document may not be completely up to date at all times.

Testing

Many of the things package perf does require elevated privileges on most systems. We would very much like for the tests to not require root to run. Because of this, we use a fairly specific testing model, described next.

If the host kernel does not support perf_event_open(2) (i.e. if the /proc/sys/kernel/perf_event_paranoid file is not present), then tests fail immediately with an error message.

Tests are designed in such a way that they are skipped if their requirements are not met by the underlying system. We would like the test suite to degrade gracefully, under certain circumstances.

For example, when running Linux in a virtualized environment, various hardware PMUs might not be available. In such situations, we would like the test suite to continue running. For this purpose, we introduce the mechanism described next.

Requirements for a test are specified by invoking the requires function, at the beginning of a test function. All tests that call perf_event_open must specify requirements this way. Currently, we use three kinds of requirements:

  • perf_event_paranoid values

  • the existence of various PMUs (e.g. "cpu", "software", "tracepoint")

  • tracefs is mounted, and readable

Today, setting perf_event_paranoid=1 and having a readable tracefs mounted at /sys/kernel/debug/tracing enables most of the tests. A select few require perf_event_paranoid=0. If the test process is running with CAP_SYS_ADMIN, perf_event_paranoid requirements are ignored, since they are considered fulfilled. The test process does not attempt to see if it is running as root, it only checks CAP_SYS_ADMIN.

If you find a test that, when ran without elevated privileges, fails with something akin to a permissions error, then it means the requirements for the test were not specified precisely. Please file a bug. Extending the test suite and making these requirements more precise is an ongoing process.

Documentation

Overview

Package perf provides access to the Linux perf API.

Counting events

A Group represents a set of perf events measured together. 

var g perf.Group
g.Add(perf.Instructions, perf.CPUCycles)

hw, err := g.Open(targetpid, perf.AnyCPU)
// ...
gc, err := hw.MeasureGroup(func() { ... })

Attr configures an individual event. 

fa := &perf.Attr{
	CountFormat: perf.CountFormat{
		Running: true,
		ID:      true,
	},
}
perf.PageFaults.Configure(fa)

faults, err := perf.Open(fa, perf.CallingThread, perf.AnyCPU, nil)
// ...
c, err := faults.Measure(func() { ... })

Sampling events

Overflow records are available once the MapRing method on Event is called: 

var ev perf.Event // initialized previously

ev.MapRing()

ev.Enable()

ctx, cancel := context.WithTimeout(context.Background(), 1*time.Second)
defer cancel()

for {
	rec, err := ev.ReadRecord(ctx)
	// process rec
}

Tracepoints are also supported: 

wa := &perf.Attr{
	SampleFormat: perf.SampleFormat{
		Pid: true,
		Tid: true,
		IP:  true,
	},
}
wa.SetSamplePeriod(1)
wa.SetWakeupEvents(1)
wtp := perf.Tracepoint("syscalls", "sys_enter_write")
wtp.Configure(wa)

writes, err := perf.Open(wa, targetpid, perf.AnyCPU, nil)
// ...
c, err := writes.Measure(func() { ... })
// ...
fmt.Printf("saw %d writes\n", c.Value)

rec, err := writes.ReadRecord(ctx)
// ...
sr, ok := rec.(*perf.SampleRecord)
// ...
fmt.Printf("pid = %d, tid = %d\n", sr.Pid, sr.Tid)

For more detailed information, see the examples, and man 2 perf_event_open.

NOTE: this package is experimental and does not yet offer compatibility guarantees.

Index

Examples

Constants

View Source 
const (
	// CallingThread configures the event to measure the calling thread.
	CallingThread = 0

	// AllThreads configures the event to measure all threads on the
	// specified CPU.
	AllThreads = -1
)

Special pid values for Open.

View Source 
const AnyCPU = -1

AnyCPU configures the specified process/thread to be measured on any CPU.

View Source 
const DefaultNumPages = 128

DefaultNumPages is the number of pages used by MapRing. There is no fundamental logic to this number. We use it because that is what the perf tool does.

Variables

View Source 
var ErrBadRecord = errors.New("bad record received")

ErrBadRecord is returned by ReadRecord when a read record can't be decoded.

View Source 
var ErrDisabled = errors.New("perf: event disabled")

ErrDisabled is returned from ReadRecord and ReadRawRecord if the event being monitored is attached to a different process, and that process exits. (since Linux 3.18)

View Source 
var ErrNoReadRecord = errors.New("perf: ReadRecord disabled")

ErrNoReadRecord is returned by ReadRecord when it is disabled on a group event, due to different configurations of the leader and follower events. See also (*Event).SetOutput.

Functions

func LookupTracepointConfig 

func LookupTracepointConfig(category, event string) (uint64, error)

LookupTracepointConfig probes /sys/kernel/debug/tracing/events/<category>/<event>/id for the Attr.Config value associated with the specified category and event.

func MaxStack 

func MaxStack() (uint16, error)

MaxStack returns the maximum number of frame pointers in a recorded callchain. It reads the value from /proc/sys/kernel/perf_event_max_stack.

func Supported 

func Supported() bool

Supported returns a boolean indicating whether the host kernel supports the perf_event_open system call, which is a prerequisite for the operations of this package.

Supported checks for the existence of a /proc/sys/kernel/perf_event_paranoid file, which is the canonical method for determining if a kernel supports perf_event_open(2).

Types

type Attr 

type Attr struct {
	// Label is a human readable label associated with the event.
	// For convenience, the Label is included in Count and GroupCount
	// measurements read from events.
	//
	// When an event is opened, if Label is the empty string, then a
	// Label is computed (if possible) based on the Type and Config
	// fields. Otherwise, if the Label user-defined (not the empty
	// string), it is included verbatim.
	//
	// For most events, the computed Label matches the label specified by
	// “perf list” for the same event (but see Bugs).
	Label string

	// Type is the major type of the event.
	Type EventType

	// Config is the type-specific event configuration.
	Config uint64

	// Sample configures the sample period or sample frequency for
	// overflow packets, based on Options.Freq: if Options.Freq is set,
	// Sample is interpreted as "sample frequency", otherwise it is
	// interpreted as "sample period".
	//
	// See also SetSample{Period,Freq}.
	Sample uint64

	// SampleFormat configures information requested in sample records,
	// on the memory mapped ring buffer.
	SampleFormat SampleFormat

	// CountFormat specifies the format of counts read from the
	// Event using ReadCount or ReadGroupCount. See the CountFormat
	// documentation for more details.
	CountFormat CountFormat

	// Options contains more fine grained event configuration.
	Options Options

	// Wakeup configures wakeups on the ring buffer associated with the
	// event. If Options.Watermark is set, Wakeup is interpreted as the
	// number of bytes before wakeup. Otherwise, it is interpreted as
	// "wake up every N events".
	//
	// See also SetWakeup{Events,Watermark}.
	Wakeup uint32

	// BreakpointType is the breakpoint type, if Type == BreakpointEvent.
	BreakpointType uint32

	// Config1 is used for events that need an extra register or otherwise
	// do not fit in the regular config field.
	//
	// For breakpoint events, Config1 is the breakpoint address.
	// For kprobes, it is the kprobe function. For uprobes, it is the
	// uprobe path.
	Config1 uint64

	// Config2 is a further extension of the Config1 field.
	//
	// For breakpoint events, it is the length of the breakpoint.
	// For kprobes, when the kprobe function is NULL, it is the address of
	// the kprobe. For both kprobes and uprobes, it is the probe offset.
	Config2 uint64

	// BranchSampleFormat specifies what branches to include in the
	// branch record, if SampleFormat.BranchStack is set.
	BranchSampleFormat BranchSampleFormat

	// SampleRegistersUser is the set of user registers to dump on samples.
	SampleRegistersUser uint64

	// SampleStackUser is the size of the user stack to  dump on samples.
	SampleStackUser uint32

	// ClockID is the clock ID to use with samples, if Options.UseClockID
	// is set.
	//
	// TODO(acln): What are the values for this? CLOCK_MONOTONIC and such?
	// Investigate. Can we choose a clock that can be compared to Go's
	// clock in a meaningful way? If so, should we add special support
	// for that?
	ClockID int32

	// SampleRegistersIntr is the set of register to dump for each sample.
	// See asm/perf_regs.h for details.
	SampleRegistersIntr uint64

	// AuxWatermark is the watermark for the aux area.
	AuxWatermark uint32

	// SampleMaxStack is the maximum number of frame pointers in a
	// callchain. The value must be < MaxStack().
	SampleMaxStack uint16
}

Attr configures a perf event.

func (*Attr) Configure 

func (a *Attr) Configure(target *Attr) error

Configure implements the Configurator interface. It overwrites target with a. See also (*Group).Add.

func (*Attr) SetSampleFreq 

func (a *Attr) SetSampleFreq(f uint64)

SetSampleFreq configures the sampling frequency for the event.

It sets attr.Sample to f and enables a.Options.Freq.

func (*Attr) SetSamplePeriod 

func (a *Attr) SetSamplePeriod(p uint64)

SetSamplePeriod configures the sampling period for the event.

It sets attr.Sample to p and disables a.Options.Freq.

func (*Attr) SetWakeupEvents 

func (a *Attr) SetWakeupEvents(n uint32)

SetWakeupEvents configures the event to wake up every n events.

It sets a.Wakeup to n and disables a.Options.Watermark.

func (*Attr) SetWakeupWatermark 

func (a *Attr) SetWakeupWatermark(n uint32)

SetWakeupWatermark configures the number of bytes in overflow records before wakeup.

It sets a.Wakeup to n and enables a.Options.Watermark.

type AuxFlag 

type AuxFlag uint64

AuxFlag describes an update to a record in the AUX buffer region. 

const (
	AuxTruncated AuxFlag = 0x01 // record was truncated to fit
	AuxOverwrite AuxFlag = 0x02 // snapshot from overwrite mode
	AuxPartial   AuxFlag = 0x04 // record contains gaps
	AuxCollision AuxFlag = 0x08 // sample collided with another
)

AuxFlag bits.

type AuxRecord 

type AuxRecord struct {
	RecordHeader
	Offset uint64  // offset in the AUX mmap region where the new data begins
	Size   uint64  // size of data made available
	Flags  AuxFlag // describes the update
	SampleID
}

AuxRecord (PERF_RECORD_AUX) reports that new data is available in the AUX buffer region.

func (*AuxRecord) DecodeFrom 

func (ar *AuxRecord) DecodeFrom(raw *RawRecord, ev *Event) error

DecodeFrom implements the Record.DecodeFrom method.

type BranchEntry 

type BranchEntry struct {
	From             uint64
	To               uint64
	Mispredicted     bool
	Predicted        bool
	InTransaction    bool
	TransactionAbort bool
	Cycles           uint16
	BranchType       BranchType
}

BranchEntry is a sampled branch.

type BranchSample 

type BranchSample uint64

BranchSample specifies a type of branch to sample. 

const (
	BranchSampleAny              BranchSample = unix.PERF_SAMPLE_BRANCH_ANY
	BranchSampleAnyCall          BranchSample = unix.PERF_SAMPLE_BRANCH_ANY_CALL
	BranchSampleAnyReturn        BranchSample = unix.PERF_SAMPLE_BRANCH_ANY_RETURN
	BranchSampleIndirectCall     BranchSample = unix.PERF_SAMPLE_BRANCH_IND_CALL
	BranchSampleAbortTransaction BranchSample = unix.PERF_SAMPLE_BRANCH_ABORT_TX
	BranchSampleInTransaction    BranchSample = unix.PERF_SAMPLE_BRANCH_IN_TX
	BranchSampleNoTransaction    BranchSample = unix.PERF_SAMPLE_BRANCH_NO_TX
	BranchSampleCond             BranchSample = unix.PERF_SAMPLE_BRANCH_COND
	BranchSampleCallStack        BranchSample = unix.PERF_SAMPLE_BRANCH_CALL_STACK
	BranchSampleIndirectJump     BranchSample = unix.PERF_SAMPLE_BRANCH_IND_JUMP
	BranchSampleCall             BranchSample = unix.PERF_SAMPLE_BRANCH_CALL
	BranchSampleNoFlags          BranchSample = unix.PERF_SAMPLE_BRANCH_NO_FLAGS
	BranchSampleNoCycles         BranchSample = unix.PERF_SAMPLE_BRANCH_NO_CYCLES
	BranchSampleSave             BranchSample = unix.PERF_SAMPLE_BRANCH_TYPE_SAVE
)

Branch sample bits. Values should be |-ed together.

type BranchSampleFormat 

type BranchSampleFormat struct {
	Privilege BranchSamplePrivilege
	Sample    BranchSample
}

BranchSampleFormat specifies what branches to include in a branch record.

type BranchSamplePrivilege 

type BranchSamplePrivilege uint64

BranchSamplePrivilege speifies a branch sample privilege level. If a level is not set explicitly, the kernel will use the event's privilege level. Event and branch privilege levels do not have to match. 

const (
	BranchPrivilegeUser       BranchSamplePrivilege = unix.PERF_SAMPLE_BRANCH_USER
	BranchPrivilegeKernel     BranchSamplePrivilege = unix.PERF_SAMPLE_BRANCH_KERNEL
	BranchPrivilegeHypervisor BranchSamplePrivilege = unix.PERF_SAMPLE_BRANCH_HV
)

Branch sample privilege values. Values should be |-ed together.

type BranchType 

type BranchType uint8

BranchType classifies a BranchEntry. 

const (
	BranchTypeUnknown BranchType = iota
	BranchTypeConditional
	BranchTypeUnconditional
	BranchTypeIndirect
	BranchTypeCall
	BranchTypeIndirectCall
	BranchTypeReturn
	BranchTypeSyscall
	BranchTypeSyscallReturn
	BranchTypeConditionalCall
	BranchTypeConditionalReturn
)

Branch classifications.

type BreakpointLength 

type BreakpointLength uint64

BreakpointLength is the length of the breakpoint being measured. 

const (
	BreakpointLength1 BreakpointLength = 1
	BreakpointLength2 BreakpointLength = 2
	BreakpointLength4 BreakpointLength = 4
	BreakpointLength8 BreakpointLength = 8
)

Breakpoint length values.

func ExecutionBreakpointLength 

func ExecutionBreakpointLength() BreakpointLength

ExecutionBreakpointLength returns the length of an execution breakpoint.

type BreakpointType 

type BreakpointType uint32

BreakpointType is the type of a breakpoint. 

const (
	BreakpointTypeEmpty BreakpointType = 0x0
	BreakpointTypeR     BreakpointType = 0x1
	BreakpointTypeW     BreakpointType = 0x2
	BreakpointTypeRW    BreakpointType = BreakpointTypeR | BreakpointTypeW
	BreakpointTypeX     BreakpointType = 0x4
)

Breakpoint types. Values are |-ed together. The combination of BreakpointTypeR or BreakpointTypeW with BreakpointTypeX is invalid.

type CPUMode 

type CPUMode uint8

CPUMode is a CPU operation mode. 

const (
	UnknownMode CPUMode = iota
	KernelMode
	UserMode
	HypervisorMode
	GuestKernelMode
	GuestUserMode
)

Known CPU modes.

type Cache 

type Cache uint64

Cache identifies a cache. 

const (
	L1D  Cache = unix.PERF_COUNT_HW_CACHE_L1D
	L1I  Cache = unix.PERF_COUNT_HW_CACHE_L1I
	LL   Cache = unix.PERF_COUNT_HW_CACHE_LL
	DTLB Cache = unix.PERF_COUNT_HW_CACHE_DTLB
	ITLB Cache = unix.PERF_COUNT_HW_CACHE_ITLB
	BPU  Cache = unix.PERF_COUNT_HW_CACHE_BPU
	NODE Cache = unix.PERF_COUNT_HW_CACHE_NODE
)

Caches.

func AllCaches 

func AllCaches() []Cache

AllCaches returns a slice of all known cache types.

type CacheOp 

type CacheOp uint64

CacheOp is a cache operation. 

const (
	Read     CacheOp = unix.PERF_COUNT_HW_CACHE_OP_READ
	Write    CacheOp = unix.PERF_COUNT_HW_CACHE_OP_WRITE
	Prefetch CacheOp = unix.PERF_COUNT_HW_CACHE_OP_PREFETCH
)

Cache operations.

func AllCacheOps 

func AllCacheOps() []CacheOp

AllCacheOps returns a slice of all known cache operations.

type CacheOpResult 

type CacheOpResult uint64

CacheOpResult is the result of a cache operation. 

const (
	Access CacheOpResult = unix.PERF_COUNT_HW_CACHE_RESULT_ACCESS
	Miss   CacheOpResult = unix.PERF_COUNT_HW_CACHE_RESULT_MISS
)

Cache operation results.

func AllCacheOpResults 

func AllCacheOpResults() []CacheOpResult

AllCacheOpResults returns a slice of all known cache operation results.

type CommRecord 

type CommRecord struct {
	RecordHeader
	Pid     uint32 // process ID
	Tid     uint32 // threadID
	NewName string // the new name of the process
	SampleID
}

CommRecord (PERF_RECORD_COMM) indicates a change in the process name.

func (*CommRecord) DecodeFrom 

func (cr *CommRecord) DecodeFrom(raw *RawRecord, ev *Event) error

DecodeFrom implements the Record.DecodeFrom method.

func (*CommRecord) WasExec 

func (cr *CommRecord) WasExec() bool

WasExec returns a boolean indicating whether a process name change was caused by an exec(2) system call.

type Configurator 

type Configurator interface {
	Configure(attr *Attr) error
}

A Configurator configures event attributes. Implementations should only set the fields they need. See (*Group).Add for more details.

func AllHardwareCounters 

func AllHardwareCounters() []Configurator

AllHardwareCounters returns a slice of all known hardware counters.

func AllSoftwareCounters 

func AllSoftwareCounters() []Configurator

AllSoftwareCounters returns a slice of all known software counters.

func Breakpoint 

func Breakpoint(typ BreakpointType, addr uint64, length BreakpointLength) Configurator

Breakpoint returns a Configurator for a breakpoint event.

typ is the type of the breakpoint.

addr is the address of the breakpoint. For execution breakpoints, this is the memory address of the instruction of interest; for read and write breakpoints, it is the memory address of the memory location of interest.

length is the length of the breakpoint being measured.

The returned Configurator sets the Type, BreakpointType, Config1, and Config2 fields on attr.

func ExecutionBreakpoint 

func ExecutionBreakpoint(addr uint64) Configurator

ExecutionBreakpoint returns a Configurator for an execution breakpoint at the specified address.

func HardwareCacheCounters 

func HardwareCacheCounters(caches []Cache, ops []CacheOp, results []CacheOpResult) []Configurator

HardwareCacheCounters returns cache counters which measure the cartesian product of the specified caches, operations and results.

func Tracepoint 

func Tracepoint(category, event string) Configurator

Tracepoint returns a Configurator for the specified category and event. The returned Configurator sets attr.Type and attr.Config.

Example (Getpid) 
ga := new(perf.Attr)
gtp := perf.Tracepoint("syscalls", "sys_enter_getpid")
if err := gtp.Configure(ga); err != nil {
	log.Fatal(err)
}

runtime.LockOSThread()
defer runtime.UnlockOSThread()

getpid, err := perf.Open(ga, perf.CallingThread, perf.AnyCPU, nil)
if err != nil {
	log.Fatal(err)
}
defer getpid.Close()

unix.Getpid() // does not count towards the measurement

c, err := getpid.Measure(func() {
	unix.Getpid()
	unix.Getpid()
	unix.Getpid()
})
if err != nil {
	log.Fatal(err)
}

fmt.Printf("saw getpid %d times\n", c.Value) // should print 3

Output:

type Count 

type Count struct {
	Value   uint64
	Enabled time.Duration
	Running time.Duration
	ID      uint64
	Label   string
}

Count is a measurement taken by an Event.

The Value field is always present and populated.

The Enabled field is populated if CountFormat.Enabled is set on the Event the Count was read from. Ditto for TimeRunning and ID.

Label is set based on the Label field of the Attr associated with the event. See the documentation there for more details.

func (Count) String 

func (c Count) String() string

type CountFormat 

type CountFormat struct {
	Enabled bool
	Running bool
	ID      bool
	Group   bool
}

CountFormat configures the format of Count or GroupCount measurements.

Enabled and Running configure the Event to include time enabled and time running measurements to the counts. Usually, these two values are equal. They may differ when events are multiplexed.

If ID is set, a unique ID is assigned to the associated event. For a given event, this ID matches the ID reported by the (*Event).ID method.

If Group is set, the Event measures a group of events together: callers must use ReadGroupCount. If Group is not set, the Event measures a single counter: callers must use ReadCount.

type DataSource 

type DataSource uint64

DataSource records where in the memory hierarchy the data associated with a sampled instruction came from.

func (DataSource) MemLevel 

func (ds DataSource) MemLevel() MemLevel

MemLevel returns the recorded memory level.

func (DataSource) MemLevelNumber 

func (ds DataSource) MemLevelNumber() MemLevelNumber

MemLevelNumber returns the recorded memory level number.

func (DataSource) MemLock 

func (ds DataSource) MemLock() MemLock

MemLock returns the recorded memory lock mode.

func (DataSource) MemOp 

func (ds DataSource) MemOp() MemOp

MemOp returns the recorded memory operation.

func (DataSource) MemRemote 

func (ds DataSource) MemRemote() MemRemote

MemRemote returns the recorded remote bit.

func (DataSource) MemSnoopMode 

func (ds DataSource) MemSnoopMode() MemSnoopMode

MemSnoopMode returns the recorded memory snoop mode.

func (DataSource) MemSnoopModeX 

func (ds DataSource) MemSnoopModeX() MemSnoopModeX

MemSnoopModeX returns the recorded extended memory snoop mode.

func (DataSource) MemTLB 

func (ds DataSource) MemTLB() MemTLB

MemTLB returns the recorded TLB access mode.

type Event 

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

Event is an active perf event.

func Open 

func Open(a *Attr, pid, cpu int, group *Event) (*Event, error)

Open opens the event configured by attr.

The pid and cpu parameters specify which thread and CPU to monitor:

  • if pid == CallingThread and cpu == AnyCPU, the event measures the calling thread on any CPU

  • if pid == CallingThread and cpu >= 0, the event measures the calling thread only when running on the specified CPU

  • if pid > 0 and cpu == AnyCPU, the event measures the specified thread on any CPU

  • if pid > 0 and cpu >= 0, the event measures the specified thread only when running on the specified CPU

  • if pid == AllThreads and cpu >= 0, the event measures all threads on the specified CPU

  • finally, the pid == AllThreads and cpu == AnyCPU setting is invalid

If group is non-nil, the returned Event is made part of the group associated with the specified group Event.

func OpenCGroup 

func OpenCGroup(a *Attr, cgroupfd, cpu int, group *Event) (*Event, error)

OpenCGroup is like Open, but activates per-container system-wide monitoring. If cgroupfs is mounted on /dev/cgroup, and the group to monitor is called "test", then cgroupfd must be a file descriptor opened on /dev/cgroup/test.

func OpenWithFlags 

func OpenWithFlags(a *Attr, pid, cpu int, group *Event, flags int) (*Event, error)

OpenWithFlags is like Open but allows to specify additional flags to be passed to perf_event_open(2).

func (*Event) Close 

func (ev *Event) Close() error

Close closes the event. Close must not be called concurrently with any other methods on the Event.

func (*Event) Disable 

func (ev *Event) Disable() error

Disable disables the event. If ev is a group leader, Disable disables all events in the group.

func (*Event) Enable 

func (ev *Event) Enable() error

Enable enables the event.

func (*Event) FD 

func (ev *Event) FD() (int, error)

FD returns the file descriptor associated with the event.

func (*Event) HasRecord 

func (ev *Event) HasRecord() bool

HasRecord returns if there is a record available to be read from the ring.

func (*Event) ID 

func (ev *Event) ID() (uint64, error)

ID returns the unique event ID value for ev.

func (*Event) MapRing 

func (ev *Event) MapRing() error

MapRing maps the ring buffer attached to the event into memory.

This enables reading records via ReadRecord / ReadRawRecord.

func (*Event) MapRingNumPages 

func (ev *Event) MapRingNumPages(num int) error

MapRingNumPages is like MapRing, but allows the caller to The size of the data portion of the ring is num pages. The total size of the ring is num+1 pages, because an additional metadata page is mapped before the data portion of the ring.

func (*Event) Measure 

func (ev *Event) Measure(f func()) (Count, error)

Measure disables the event, resets it, enables it, runs f, disables it again, then reads the Count associated with the event.

func (*Event) MeasureGroup 

func (ev *Event) MeasureGroup(f func()) (GroupCount, error)

MeasureGroup is like Measure, but for event groups.

func (*Event) PauseOutput 

func (ev *Event) PauseOutput() error

PauseOutput pauses the output from ev.

func (*Event) QueryBPF 

func (ev *Event) QueryBPF(max uint32) ([]uint32, error)

QueryBPF queries the event for BPF program file descriptors attached to the same tracepoint as ev. max is the maximum number of file descriptors to return.

func (*Event) ReadCount 

func (ev *Event) ReadCount() (Count, error)

ReadCount reads the measurement associated with ev. If the Event was configured with CountFormat.Group, ReadCount returns an error.

func (*Event) ReadGroupCount 

func (ev *Event) ReadGroupCount() (GroupCount, error)

ReadGroupCount reads the measurements associated with ev. If the Event was not configued with CountFormat.Group, ReadGroupCount returns an error.

func (*Event) ReadRawRecord 

func (ev *Event) ReadRawRecord(ctx context.Context, raw *RawRecord) error

ReadRawRecord reads and decodes a raw record from the ring buffer associated with ev into rec. Callers must not retain rec.Data.

ReadRawRecord may be called concurrently with ReadCount or ReadGroupCount, but not concurrently with itself, ReadRecord, Close or any other Event method.

func (*Event) ReadRecord 

func (ev *Event) ReadRecord(ctx context.Context) (Record, error)

ReadRecord reads and decodes a record from the ring buffer associated with ev.

ReadRecord may be called concurrently with ReadCount or ReadGroupCount, but not concurrently with itself, ReadRawRecord, Close, or any other Event method.

If another event's records were routed to ev via SetOutput, and the two events did not have compatible SampleFormat Options settings (see SetOutput documentation), ReadRecord returns ErrNoReadRecord.

func (*Event) Refresh 

func (ev *Event) Refresh(delta int) error

Refresh adds delta to a counter associated with the event. This counter decrements every time the event overflows. Once the counter reaches zero, the event is disabled. Calling Refresh with delta == 0 is considered undefined behavior.

func (*Event) Reset 

func (ev *Event) Reset() error

Reset resets the counters associated with the event.

func (*Event) ResumeOutput 

func (ev *Event) ResumeOutput() error

ResumeOutput resumes output from ev.

func (*Event) SetBPF 

func (ev *Event) SetBPF(progfd uint32) error

SetBPF attaches a BPF program to ev, which must be a kprobe tracepoint event. progfd is the file descriptor associated with the BPF program.

func (*Event) SetOutput 

func (ev *Event) SetOutput(target *Event) error

SetOutput tells the kernel to send records to the specified target Event rather than ev.

If target is nil, output from ev is ignored.

Some restrictions apply:

1) Calling SetOutput on an *Event will fail with EINVAL if MapRing was called on that event previously. 2) If ev and target are not CPU-wide events, they must be on the same CPU. 3) If ev and target are CPU-wide events, they must refer to the same task. 4) ev and target must use the same clock.

An additional restriction of the Go API also applies:

In order to use ReadRecord on the target Event, the following settings on ev and target must match: Options.SampleIDAll, SampleFormat.Identifier, SampleFormat.IP, SampleFormat.Tid, SampleFormat.Time, SampleFormat.Addr, SampleFormat.ID, SampleFormat.StreamID. Furthermore, SampleFormat.StreamID must be set. SetOutput nevertheless succeeds even if this condition is not met, because callers can still use ReadRawRecord instead of ReadRecord.

func (*Event) UpdatePeriod 

func (ev *Event) UpdatePeriod(p uint64) error

UpdatePeriod updates the overflow period for the event. On older kernels, the new period does not take effect until after the next overflow.

type EventType 

type EventType uint32

EventType is the overall type of a performance event. 

const (
	HardwareEvent      EventType = unix.PERF_TYPE_HARDWARE
	SoftwareEvent      EventType = unix.PERF_TYPE_SOFTWARE
	TracepointEvent    EventType = unix.PERF_TYPE_TRACEPOINT
	HardwareCacheEvent EventType = unix.PERF_TYPE_HW_CACHE
	RawEvent           EventType = unix.PERF_TYPE_RAW
	BreakpointEvent    EventType = unix.PERF_TYPE_BREAKPOINT
)

Supported event types.

func LookupEventType 

func LookupEventType(pmu string) (EventType, error)

LookupEventType probes /sys/bus/event_source/devices/<device>/type for the EventType value associated with the specified PMU.

type ExitRecord 

type ExitRecord struct {
	RecordHeader
	Pid  uint32 // process ID
	Ppid uint32 // parent process ID
	Tid  uint32 // thread ID
	Ptid uint32 // parent thread ID
	Time uint64 // time when the process exited
	SampleID
}

ExitRecord (PERF_RECORD_EXIT) indicates a process exit event.

func (*ExitRecord) DecodeFrom 

func (er *ExitRecord) DecodeFrom(raw *RawRecord, ev *Event) error

DecodeFrom implements the Record.DecodeFrom method.

type ForkRecord 

type ForkRecord struct {
	RecordHeader
	Pid  uint32 // process ID
	Ppid uint32 // parent process ID
	Tid  uint32 // thread ID
	Ptid uint32 // parent thread ID
	Time uint64 // time when the fork occurred
	SampleID
}

ForkRecord (PERF_RECORD_FORK) indicates a fork event.

func (*ForkRecord) DecodeFrom 

func (fr *ForkRecord) DecodeFrom(raw *RawRecord, ev *Event) error

DecodeFrom implements the Record.DecodeFrom method.

type Group 

type Group struct {
	// CountFormat configures the format of counts read from the event
	// leader. The Group option is set automatically.
	CountFormat CountFormat

	// Options configures options for all events in the group.
	Options Options

	// ClockID configures the clock for samples in the group.
	ClockID int32
	// contains filtered or unexported fields
}

Group configures a group of events.

func (*Group) Add 

func (g *Group) Add(cfgs ...Configurator)

Add adds events to the group, as configured by cfgs.

For each Configurator, a new *Attr is created, the group-specific settings are applied, then Configure is called on the *Attr to produce the final event attributes.

func (*Group) Open 

func (g *Group) Open(pid int, cpu int) (*Event, error)

Open opens all the events in the group, and returns their leader.

The returned Event controls the entire group. Callers must use the ReadGroupCount method when reading counters from it. Closing it closes the entire group.

type GroupCount 

type GroupCount struct {
	Enabled time.Duration
	Running time.Duration
	Values  []struct {
		Value uint64
		ID    uint64
		Label string
	}
}

GroupCount is a group of measurements taken by an Event group.

Fields are populated as described in the Count documentation.

func (GroupCount) PrintValues 

func (gc GroupCount) PrintValues(w io.Writer) error

PrintValues prints a table of gc.Values to w.

type HardwareCacheCounter 

type HardwareCacheCounter struct {
	Cache  Cache
	Op     CacheOp
	Result CacheOpResult
}

A HardwareCacheCounter groups a cache, a cache operation, and an operation result. It measures the number of results for the specified op, on the specified cache.

func (HardwareCacheCounter) Configure 

func (hwcc HardwareCacheCounter) Configure(attr *Attr) error

Configure configures attr to measure hwcc. It sets attr.Type and attr.Config.

type HardwareCounter 

type HardwareCounter uint64

HardwareCounter is a hardware performance counter.

Example (IPC) 
g := perf.Group{
	CountFormat: perf.CountFormat{
		Running: true,
	},
}
g.Add(perf.Instructions, perf.CPUCycles)

runtime.LockOSThread()
defer runtime.UnlockOSThread()

ipc, err := g.Open(perf.CallingThread, perf.AnyCPU)
if err != nil {
	log.Fatal(err)
}
defer ipc.Close()

sum := 0
gc, err := ipc.MeasureGroup(func() {
	for i := 0; i < 100000; i++ {
		sum += i
	}
})
if err != nil {
	log.Fatal(err)
}

insns, cycles := gc.Values[0].Value, gc.Values[1].Value

fmt.Printf("got sum = %d in %v: %d instructions, %d CPU cycles: %f IPC",
	sum, gc.Running, insns, cycles, float64(insns)/float64(cycles))

Output:


const (
	CPUCycles             HardwareCounter = unix.PERF_COUNT_HW_CPU_CYCLES
	Instructions          HardwareCounter = unix.PERF_COUNT_HW_INSTRUCTIONS
	CacheReferences       HardwareCounter = unix.PERF_COUNT_HW_CACHE_REFERENCES
	CacheMisses           HardwareCounter = unix.PERF_COUNT_HW_CACHE_MISSES
	BranchInstructions    HardwareCounter = unix.PERF_COUNT_HW_BRANCH_INSTRUCTIONS
	BranchMisses          HardwareCounter = unix.PERF_COUNT_HW_BRANCH_MISSES
	BusCycles             HardwareCounter = unix.PERF_COUNT_HW_BUS_CYCLES
	StalledCyclesFrontend HardwareCounter = unix.PERF_COUNT_HW_STALLED_CYCLES_FRONTEND
	StalledCyclesBackend  HardwareCounter = unix.PERF_COUNT_HW_STALLED_CYCLES_BACKEND
	RefCPUCycles          HardwareCounter = unix.PERF_COUNT_HW_REF_CPU_CYCLES
)

Hardware performance counters.

func (HardwareCounter) Configure 

func (hwc HardwareCounter) Configure(attr *Attr) error

Configure configures attr to measure hwc. It sets the Label, Type, and Config fields on attr.

func (HardwareCounter) String 

func (hwc HardwareCounter) String() string

type ItraceStartRecord 

type ItraceStartRecord struct {
	RecordHeader
	Pid uint32 // process ID of the thread starting an instruction trace
	Tid uint32 // thread ID of the thread starting an instruction trace
	SampleID
}

ItraceStartRecord (PERF_RECORD_ITRACE_START) indicates which process has initiated an instruction trace event, allowing tools to correlate instruction addresses in the AUX buffer with the proper executable.

func (*ItraceStartRecord) DecodeFrom 

func (ir *ItraceStartRecord) DecodeFrom(raw *RawRecord, ev *Event) error

DecodeFrom implements the Record.DecodeFrom method.

type LostRecord 

type LostRecord struct {
	RecordHeader
	ID   uint64 // the unique ID for the lost events
	Lost uint64 // the number of lost events
	SampleID
}

LostRecord (PERF_RECORD_LOST) indicates when events are lost.

func (*LostRecord) DecodeFrom 

func (lr *LostRecord) DecodeFrom(raw *RawRecord, ev *Event) error

DecodeFrom implements the Record.DecodeFrom method.

type LostSamplesRecord 

type LostSamplesRecord struct {
	RecordHeader
	Lost uint64 // the number of potentially lost samples
	SampleID
}

LostSamplesRecord (PERF_RECORD_LOST_SAMPLES) indicates some number of samples that may have been lost, when using hardware sampling such as Intel PEBS.

func (*LostSamplesRecord) DecodeFrom 

func (lr *LostSamplesRecord) DecodeFrom(raw *RawRecord, ev *Event) error

DecodeFrom implements the Record.DecodeFrom method.

type MemLevel 

type MemLevel uint32

MemLevel is a memory level. 

const (
	MemLevelNA MemLevel = 1 << iota
	MemLevelHit
	MemLevelMiss
	MemLevelL1
	MemLevelLFB
	MemLevelL2
	MemLevelL3
	MemLevelLocalDRAM
	MemLevelRemoteDRAM1
	MemLevelRemoteDRAM2
	MemLevelRemoteCache1
	MemLevelRemoteCache2
	MemLevelIO
	MemLevelUncached
)

MemLevel flag bits.

type MemLevelNumber 

type MemLevelNumber uint8

MemLevelNumber is a memory level number. 

const (
	MemLevelNumberL1 MemLevelNumber = iota
	MemLevelNumberL2
	MemLevelNumberL3
	MemLevelNumberL4

	MemLevelNumberAnyCache MemLevelNumber = iota + 0x0b
	MemLevelNumberLFB
	MemLevelNumberRAM
	MemLevelNumberPMem
	MemLevelNumberNA
)

MemLevelNumber flag bits.

type MemLock 

type MemLock uint8

MemLock is a memory locking mode. 

const (
	MemLockNA     MemLock = 1 << iota // not available
	MemLockLocked                     // locked transaction

)

MemLock flag bits.

type MemOp 

type MemOp uint8

MemOp is a memory operation. 

const (
	MemOpNA MemOp = 1 << iota
	MemOpLoad
	MemOpStore
	MemOpPrefetch
	MemOpExec
)

MemOp flag bits.

type MemRemote 

type MemRemote uint8

MemRemote indicates whether remote memory was accessed. 

const (
	MemRemoteRemote MemRemote = 1 << iota
)

MemRemote flag bits.

type MemSnoopMode 

type MemSnoopMode uint8

MemSnoopMode is a memory snoop mode. 

const (
	MemSnoopModeNA MemSnoopMode = 1 << iota
	MemSnoopModeNone
	MemSnoopModeHit
	MemSnoopModeMiss
	MemSnoopModeHitModified
)

MemSnoopMode flag bits.

type MemSnoopModeX 

type MemSnoopModeX uint8

MemSnoopModeX is an extended memory snoop mode. 

const (
	MemSnoopModeXForward MemSnoopModeX = 0x01 // forward

)

MemSnoopModeX flag bits.

type MemTLB 

type MemTLB uint8

MemTLB is a TLB access mode. 

const (
	MemTLBNA   MemTLB = 1 << iota // not available
	MemTLBHit                     // hit level
	MemTLBMiss                    // miss level
	MemTLBL1
	MemTLBL2
	MemTLBWK // Hardware Walker
	MemTLBOS // OS fault handler

)

MemTLB flag bits.

type Mmap2Record 

type Mmap2Record struct {
	RecordHeader
	Pid             uint32 // process ID
	Tid             uint32 // thread ID
	Addr            uint64 // address of the allocated memory
	Len             uint64 // length of the allocated memory
	PageOffset      uint64 // page offset of the allocated memory
	MajorID         uint32 // major ID of the underlying device
	MinorID         uint32 // minor ID of the underlying device
	Inode           uint64 // inode number
	InodeGeneration uint64 // inode generation
	Prot            uint32 // protection information
	Flags           uint32 // flags information
	Filename        string // describes the backing of the allocated memory
	SampleID
}

Mmap2Record (PERF_RECORD_MMAP2) includes extended information on mmap(2) calls returning executable mappings. It is similar to MmapRecord, but includes extra values, allowing unique identification of shared mappings.

func (*Mmap2Record) DecodeFrom 

func (mr *Mmap2Record) DecodeFrom(raw *RawRecord, ev *Event) error

DecodeFrom implements the Record.DecodeFrom method.

func (*Mmap2Record) Executable 

func (mr *Mmap2Record) Executable() bool

Executable returns a boolean indicating whether the mapping is executable.

type MmapRecord 

type MmapRecord struct {
	RecordHeader
	Pid        uint32 // process ID
	Tid        uint32 // thread ID
	Addr       uint64 // address of the allocated memory
	Len        uint64 // length of the allocated memory
	PageOffset uint64 // page offset of the allocated memory
	Filename   string // describes backing of allocated memory
	SampleID
}

MmapRecord (PERF_RECORD_MMAP) records PROT_EXEC mappings such that user-space IPs can be correlated to code.

Example (Plugin) 
var targetpid int // pid of the monitored process

da := &perf.Attr{
	Options: perf.Options{
		Mmap: true,
	},
}
da.SetSamplePeriod(1)
da.SetWakeupEvents(1)
perf.Dummy.Configure(da) // configure a dummy event, so we can Open it

mmap, err := perf.Open(da, targetpid, perf.AnyCPU, nil)
if err != nil {
	log.Fatal(err)
}
if err := mmap.MapRing(); err != nil {
	log.Fatal(err)
}

// Monitor the target process, wait for it to load something like
// a plugin, or a shared library, which requires a PROT_EXEC mapping.

for {
	rec, err := mmap.ReadRecord(context.Background())
	if err != nil {
		log.Fatal(err)
	}
	mr, ok := rec.(*perf.MmapRecord)
	if !ok {
		continue
	}
	fmt.Printf("pid %d created a PROT_EXEC mapping at %#x: %s",
		mr.Pid, mr.Addr, mr.Filename)
}

Output:

func (*MmapRecord) DecodeFrom 

func (mr *MmapRecord) DecodeFrom(raw *RawRecord, ev *Event) error

DecodeFrom implements the Record.DecodeFrom method.

func (*MmapRecord) Executable 

func (mr *MmapRecord) Executable() bool

Executable returns a boolean indicating whether the mapping is executable.

type NamespacesRecord 

type NamespacesRecord struct {
	RecordHeader
	Pid        uint32
	Tid        uint32
	Namespaces []struct {
		Dev   uint64
		Inode uint64
	}
	SampleID
}

NamespacesRecord (PERF_RECORD_NAMESPACES) describes the namespaces of a process when it is created.

func (*NamespacesRecord) DecodeFrom 

func (nr *NamespacesRecord) DecodeFrom(raw *RawRecord, ev *Event) error

DecodeFrom implements the Record.DecodeFrom method.

type Options 

type Options struct {
	// Disabled disables the event by default. If the event is in a
	// group, but not a group leader, this option has no effect, since
	// the group leader controls when events are enabled or disabled.
	Disabled bool

	// Inherit specifies that this counter should count events of child
	// tasks as well as the specified task. This only applies to new
	// children, not to any existing children at the time the counter
	// is created (nor to any new children of existing children).
	//
	// Inherit does not work with some combination of CountFormat options,
	// such as CountFormat.Group.
	Inherit bool

	// Pinned specifies that the counter should always be on the CPU if
	// possible. This bit applies only to hardware counters, and only
	// to group leaders. If a pinned counter canno be put onto the CPU,
	// then the counter goes into an error state, where reads return EOF,
	// until it is subsequently enabled or disabled.
	Pinned bool

	// Exclusive specifies that when this counter's group is on the CPU,
	// it should be the only group using the CPUs counters.
	Exclusive bool

	// ExcludeUser excludes events that happen in user space.
	ExcludeUser bool

	// ExcludeKernel excludes events that happen in kernel space.
	ExcludeKernel bool

	// ExcludeHypervisor excludes events that happen in the hypervisor.
	ExcludeHypervisor bool

	// ExcludeIdle disables counting while the CPU is idle.
	ExcludeIdle bool

	// The mmap bit enables generation of MmapRecord records for every
	// mmap(2) call that has PROT_EXEC set.
	Mmap bool

	// Comm enables tracking of process command name, as modified by
	// exec(2), prctl(PR_SET_NAME), as well as writing to /proc/self/comm.
	// If CommExec is also set, then the CommRecord records produced
	// can be queries using the WasExec method, to differentiate exec(2)
	// from the other ases.
	Comm bool

	// Freq configures the event to use sample frequency, rather than
	// sample period. See also Attr.Sample.
	Freq bool

	// InheritStat enables saving of event counts on context switch for
	// inherited tasks. InheritStat is only meaningful if Inherit is
	// also set.
	InheritStat bool

	// EnableOnExec configures the counter to be enabled automatically
	// after a call to exec(2).
	EnableOnExec bool

	// Task configures the event to include fork/exit notifications in
	// the ring buffer.
	Task bool

	// Watermark configures the ring buffer to issue an overflow
	// notification when the Wakeup boundary is crossed. If not set,
	// notifications happen after Wakeup samples. See also Attr.Wakeup.
	Watermark bool

	// PreciseIP controls the number of instructions between an event of
	// interest happening and the kernel being able to stop and record
	// the event.
	PreciseIP Skid

	// MmapData is the counterpart to Mmap. It enables generation of
	// MmapRecord records for mmap(2) calls that do not have PROT_EXEC
	// set.
	MmapData bool

	// SampleIDAll configures Tid, Time, ID, StreamID and CPU samples
	// to be included in non-Sample records.
	SampleIDAll bool

	// ExcludeHost configures only events happening inside a guest
	// instance (one that has executed a KVM_RUN ioctl) to be measured.
	ExcludeHost bool

	// ExcludeGuest is the opposite of ExcludeHost: it configures only
	// events outside a guest instance to be measured.
	ExcludeGuest bool

	// ExcludeKernelCallchain excludes kernel callchains.
	ExcludeKernelCallchain bool

	// ExcludeUserCallchain excludes user callchains.
	ExcludeUserCallchain bool

	// Mmap2 configures mmap(2) events to include inode data.
	Mmap2 bool

	// CommExec allows the distinction between process renaming
	// via exec(2) or via other means. See also Comm, and
	// (*CommRecord).WasExec.
	CommExec bool

	// UseClockID allows selecting which internal linux clock to use
	// when generating timestamps via the ClockID field.
	UseClockID bool

	// ContextSwitch enables the generation of SwitchRecord records,
	// and SwitchCPUWideRecord records when sampling in CPU-wide mode.
	ContextSwitch bool

	// Namespaces enables the generation of NamespacesRecord records.
	Namespaces bool
	// contains filtered or unexported fields
}

Options contains low level event configuration options.

type RawRecord 

type RawRecord struct {
	Header RecordHeader
	Data   []byte
}

RawRecord is a raw overflow record, read from the memory mapped ring buffer associated with an Event.

Header is the 8 byte record header. Data contains the rest of the record.

type ReadGroupRecord 

type ReadGroupRecord struct {
	RecordHeader
	Pid        uint32     // process ID
	Tid        uint32     // thread ID
	GroupCount GroupCount // group count values
	SampleID
}

ReadGroupRecord (PERF_RECORD_READ) indicates a read event on a group event.

func (*ReadGroupRecord) DecodeFrom 

func (rr *ReadGroupRecord) DecodeFrom(raw *RawRecord, ev *Event) error

DecodeFrom implements the Record.DecodeFrom method.

type ReadRecord 

type ReadRecord struct {
	RecordHeader
	Pid   uint32 // process ID
	Tid   uint32 // thread ID
	Count Count  // count value
	SampleID
}

ReadRecord (PERF_RECORD_READ) indicates a read event.

func (*ReadRecord) DecodeFrom 

func (rr *ReadRecord) DecodeFrom(raw *RawRecord, ev *Event) error

DecodeFrom implements the Record.DecodeFrom method.

type Record 

type Record interface {
	Header() RecordHeader
	DecodeFrom(*RawRecord, *Event) error
}

Record is the interface implemented by all record types.

type RecordHeader 

type RecordHeader struct {
	Type RecordType
	Misc uint16
	Size uint16
}

RecordHeader is the header present in every overflow record.

func (RecordHeader) CPUMode 

func (rh RecordHeader) CPUMode() CPUMode

CPUMode returns the CPU mode in use when the sample happened.

func (RecordHeader) Header 

func (rh RecordHeader) Header() RecordHeader

Header returns rh itself, so that types which embed a RecordHeader automatically implement a part of the Record interface.

type RecordType 

type RecordType uint32

RecordType is the type of an overflow record. 

const (
	RecordTypeMmap          RecordType = unix.PERF_RECORD_MMAP
	RecordTypeLost          RecordType = unix.PERF_RECORD_LOST
	RecordTypeComm          RecordType = unix.PERF_RECORD_COMM
	RecordTypeExit          RecordType = unix.PERF_RECORD_EXIT
	RecordTypeThrottle      RecordType = unix.PERF_RECORD_THROTTLE
	RecordTypeUnthrottle    RecordType = unix.PERF_RECORD_UNTHROTTLE
	RecordTypeFork          RecordType = unix.PERF_RECORD_FORK
	RecordTypeRead          RecordType = unix.PERF_RECORD_READ
	RecordTypeSample        RecordType = unix.PERF_RECORD_SAMPLE
	RecordTypeMmap2         RecordType = unix.PERF_RECORD_MMAP2
	RecordTypeAux           RecordType = unix.PERF_RECORD_AUX
	RecordTypeItraceStart   RecordType = unix.PERF_RECORD_ITRACE_START
	RecordTypeLostSamples   RecordType = unix.PERF_RECORD_LOST_SAMPLES
	RecordTypeSwitch        RecordType = unix.PERF_RECORD_SWITCH
	RecordTypeSwitchCPUWide RecordType = unix.PERF_RECORD_SWITCH_CPU_WIDE
	RecordTypeNamespaces    RecordType = unix.PERF_RECORD_NAMESPACES
)

Known record types.

type SampleFormat 

type SampleFormat struct {
	// IP records the instruction pointer.
	IP bool

	// Tid records process and thread IDs.
	Tid bool

	// Time records a hardware timestamp.
	Time bool

	// Addr records an address, if applicable.
	Addr bool

	// Count records counter values for all events in a group, not just
	// the group leader.
	Count bool

	// Callchain records the stack backtrace.
	Callchain bool

	// ID records a unique ID for the opened event's group leader.
	ID bool

	// CPU records the CPU number.
	CPU bool

	// Period records the current sampling period.
	Period bool

	// StreamID returns a unique ID for the opened event. Unlike ID,
	// the actual ID is returned, not the group ID.
	StreamID bool

	// Raw records additional data, if applicable. Usually returned by
	// tracepoint events.
	Raw bool

	// BranchStack provides a record of recent branches, as provided by
	// CPU branch sampling hardware. See also Attr.BranchSampleFormat.
	BranchStack bool

	// UserRegisters records the current user-level CPU state (the
	// values in the process before the kernel was called). See also
	// Attr.SampleRegistersUser.
	UserRegisters bool

	// UserStack records the user level stack, allowing stack unwinding.
	UserStack bool

	// Weight records a hardware provided weight value that expresses
	// how costly the sampled event was.
	Weight bool

	// DataSource records the data source: where in the memory hierarchy
	// the data associated with the sampled instruction came from.
	DataSource bool

	// Identifier places the ID value in a fixed position in the record.
	Identifier bool

	// Transaction records reasons for transactional memory abort events.
	Transaction bool

	// IntrRegisters Records a subset of the current CPU register state.
	// Unlike UserRegisters, the registers will return kernel register
	// state if the overflow happened while kernel code is running. See
	// also Attr.SampleRegistersIntr.
	IntrRegisters bool

	PhysicalAddress bool
}

SampleFormat configures information requested in overflow packets.

type SampleGroupRecord 

type SampleGroupRecord struct {
	RecordHeader
	Identifier uint64
	IP         uint64
	Pid        uint32
	Tid        uint32
	Time       uint64
	Addr       uint64
	ID         uint64
	StreamID   uint64
	CPU        uint32

	Period    uint64
	Count     GroupCount
	Callchain []uint64

	Raw                  []byte
	BranchStack          []BranchEntry
	UserRegisterABI      uint64
	UserRegisters        []uint64
	UserStack            []byte
	UserStackDynamicSize uint64
	Weight               uint64
	DataSource           DataSource
	Transaction          Transaction
	IntrRegisterABI      uint64
	IntrRegisters        []uint64
	PhysicalAddress      uint64
	// contains filtered or unexported fields
}

SampleGroupRecord indicates a sample from an event group.

All the fields up to and including Callchain represent ABI bits. All the fields starting with Data are non-ABI and have no compatibility guarantees.

Fields on SampleGroupRecord are set according to the RecordFormat the event was configured with. A boolean flag in RecordFormat typically enables the homonymous field in SampleGroupRecord.

func (*SampleGroupRecord) DecodeFrom 

func (sr *SampleGroupRecord) DecodeFrom(raw *RawRecord, ev *Event) error

DecodeFrom implements the Record.DecodeFrom method.

func (*SampleGroupRecord) ExactIP 

func (sr *SampleGroupRecord) ExactIP() bool

ExactIP indicates that sr.IP points to the actual instruction that triggered the event. See also Options.PreciseIP.

type SampleID 

type SampleID struct {
	Pid      uint32
	Tid      uint32
	Time     uint64
	ID       uint64
	StreamID uint64
	CPU      uint32

	Identifier uint64
	// contains filtered or unexported fields
}

SampleID contains identifiers for when and where a record was collected.

A SampleID is included in a Record if Options.SampleIDAll is set on the associated event. Fields are set according to SampleFormat options.

type SampleRecord 

type SampleRecord struct {
	RecordHeader
	Identifier uint64
	IP         uint64
	Pid        uint32
	Tid        uint32
	Time       uint64
	Addr       uint64
	ID         uint64
	StreamID   uint64
	CPU        uint32

	Period    uint64
	Count     Count
	Callchain []uint64

	Raw                  []byte
	BranchStack          []BranchEntry
	UserRegisterABI      uint64
	UserRegisters        []uint64
	UserStack            []byte
	UserStackDynamicSize uint64
	Weight               uint64
	DataSource           DataSource
	Transaction          Transaction
	IntrRegisterABI      uint64
	IntrRegisters        []uint64
	PhysicalAddress      uint64
	// contains filtered or unexported fields
}

SampleRecord indicates a sample.

All the fields up to and including Callchain represent ABI bits. All the fields starting with Data are non-ABI and have no compatibility guarantees.

Fields on SampleRecord are set according to the SampleFormat the event was configured with. A boolean flag in SampleFormat typically enables the homonymous field in a SampleRecord.

func (*SampleRecord) DecodeFrom 

func (sr *SampleRecord) DecodeFrom(raw *RawRecord, ev *Event) error

DecodeFrom implements the Record.DecodeFrom method.

func (*SampleRecord) ExactIP 

func (sr *SampleRecord) ExactIP() bool

ExactIP indicates that sr.IP points to the actual instruction that triggered the event. See also Options.PreciseIP.

type Skid 

type Skid int

Skid is an instruction pointer skid constraint. 

const (
	CanHaveArbitrarySkid Skid = 0
	MustHaveConstantSkid Skid = 1
	RequestedZeroSkid    Skid = 2
	MustHaveZeroSkid     Skid = 3
)

Supported Skid settings.

type SoftwareCounter 

type SoftwareCounter uint64

SoftwareCounter is a software performance counter.

Example (PageFaults) 
pfa := new(perf.Attr)
perf.PageFaults.Configure(pfa)

runtime.LockOSThread()
defer runtime.UnlockOSThread()

faults, err := perf.Open(pfa, perf.CallingThread, perf.AnyCPU, nil)
if err != nil {
	log.Fatal(err)
}
defer faults.Close()

var mem []byte
const (
	size = 64 * 1024 * 1024
	pos  = 63 * 1024 * 1024
)
c, err := faults.Measure(func() {
	mem = make([]byte, size)
	mem[pos] = 42
})
if err != nil {
	log.Fatal(err)
}
fmt.Printf("saw %d page faults, wrote value %d", c.Value, mem[pos])

Output:


const (
	CPUClock        SoftwareCounter = unix.PERF_COUNT_SW_CPU_CLOCK
	TaskClock       SoftwareCounter = unix.PERF_COUNT_SW_TASK_CLOCK
	PageFaults      SoftwareCounter = unix.PERF_COUNT_SW_PAGE_FAULTS
	ContextSwitches SoftwareCounter = unix.PERF_COUNT_SW_CONTEXT_SWITCHES
	CPUMigrations   SoftwareCounter = unix.PERF_COUNT_SW_CPU_MIGRATIONS
	MinorPageFaults SoftwareCounter = unix.PERF_COUNT_SW_PAGE_FAULTS_MIN
	MajorPageFaults SoftwareCounter = unix.PERF_COUNT_SW_PAGE_FAULTS_MAJ
	AlignmentFaults SoftwareCounter = unix.PERF_COUNT_SW_ALIGNMENT_FAULTS
	EmulationFaults SoftwareCounter = unix.PERF_COUNT_SW_EMULATION_FAULTS
	Dummy           SoftwareCounter = unix.PERF_COUNT_SW_DUMMY
	BPFOutput       SoftwareCounter = unix.PERF_COUNT_SW_BPF_OUTPUT
)

Software performance counters.

func (SoftwareCounter) Configure 

func (swc SoftwareCounter) Configure(attr *Attr) error

Configure configures attr to measure swc. It sets attr.Type and attr.Config.

func (SoftwareCounter) String 

func (swc SoftwareCounter) String() string

type SwitchCPUWideRecord 

type SwitchCPUWideRecord struct {
	RecordHeader
	Pid uint32
	Tid uint32
	SampleID
}

SwitchCPUWideRecord (PERF_RECORD_SWITCH_CPU_WIDE) indicates a context switch, but only occurs when sampling in CPU-wide mode. It provides information on the process being switched to / from.

func (*SwitchCPUWideRecord) DecodeFrom 

func (sr *SwitchCPUWideRecord) DecodeFrom(raw *RawRecord, ev *Event) error

DecodeFrom implements the Record.DecodeFrom method.

func (*SwitchCPUWideRecord) Out 

func (sr *SwitchCPUWideRecord) Out() bool

Out returns a boolean indicating whether the context switch was out of the current process, or into the current process.

func (*SwitchCPUWideRecord) Preempted 

func (sr *SwitchCPUWideRecord) Preempted() bool

Preempted indicates whether the thread was preempted in TASK_RUNNING state.

type SwitchRecord 

type SwitchRecord struct {
	RecordHeader
	SampleID
}

SwitchRecord (PERF_RECORD_SWITCH) indicates that a context switch has happened.

func (*SwitchRecord) DecodeFrom 

func (sr *SwitchRecord) DecodeFrom(raw *RawRecord, ev *Event) error

DecodeFrom implements the Record.DecodeFrom method.

func (*SwitchRecord) Out 

func (sr *SwitchRecord) Out() bool

Out returns a boolean indicating whether the context switch was out of the current process, or into the current process.

func (*SwitchRecord) Preempted 

func (sr *SwitchRecord) Preempted() bool

Preempted indicates whether the thread was preempted in TASK_RUNNING state.

type ThrottleRecord 

type ThrottleRecord struct {
	RecordHeader
	Time     uint64
	ID       uint64
	StreamID uint64
	SampleID
}

ThrottleRecord (PERF_RECORD_THROTTLE) indicates a throttle event.

func (*ThrottleRecord) DecodeFrom 

func (tr *ThrottleRecord) DecodeFrom(raw *RawRecord, ev *Event) error

DecodeFrom implements the Record.DecodeFrom method.

type Transaction 

type Transaction uint64

Transaction describes a transactional memory abort. 

const (
	// Transaction Elision indicates an abort from an elision type
	// transaction (Intel CPU specific).
	TransactionElision Transaction = 1 << iota

	// TransactionGeneric indicates an abort from a generic transaction.
	TransactionGeneric

	// TransactionSync indicates a synchronous abort (related to the
	// reported instruction).
	TransactionSync

	// TransactionAsync indicates an asynchronous abort (unrelated to
	// the reported instruction).
	TransactionAsync

	// TransactionRetryable indicates whether retrying the transaction
	// may have succeeded.
	TransactionRetryable

	// TransactionConflict indicates an abort rue to memory conflicts
	// with other threads.
	TransactionConflict

	// TransactionWriteCapacity indicates an abort due to write capacity
	// overflow.
	TransactionWriteCapacity

	// TransactionReadCapacity indicates an abort due to read capacity
	// overflow.
	TransactionReadCapacity
)

Transaction bits: values should be &-ed with Transaction values.

func (Transaction) UserAbortCode 

func (txn Transaction) UserAbortCode() uint32

UserAbortCode returns the user-specified abort code associated with the transaction.

type UnthrottleRecord 

type UnthrottleRecord struct {
	RecordHeader
	Time     uint64
	ID       uint64
	StreamID uint64
	SampleID
}

UnthrottleRecord (PERF_RECORD_UNTHROTTLE) indicates an unthrottle event.

func (*UnthrottleRecord) DecodeFrom 

func (ur *UnthrottleRecord) DecodeFrom(raw *RawRecord, ev *Event) error

DecodeFrom implements the Record.DecodeFrom method.

Notes

Bugs

  • PERF_EVENT_IOC_SET_FILTER is not implemented

  • PERF_EVENT_IOC_MODIFY_ATTRIBUTES is not implemented

  • generic Attr.Label lookup is not implemented

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.