perf

package
v0.16.0-alpha Latest Latest
Warning

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

 Go to latest Published: Aug 24, 2020 License: Apache-2.0 Imports: 25 Imported by: 0

Documentation

Index

Constants

View Source 
const (
	TFD_TIMER_ABSTIME       = 1 << 0
	TFD_TIMER_CANCEL_ON_SET = 1 << 1
	TFD_CLOEXEC             = syscall.O_CLOEXEC
	TFD_NONBLOCK            = syscall.O_NONBLOCK
)

linux/timerfd.h constants

View Source 
const (
	PERF_EVENT_IOC_ENABLE       uintptr = 0x2400 + 0
	PERF_EVENT_IOC_DISABLE              = 0x2400 + 1
	PERF_EVENT_IOC_REFRESH              = 0x2400 + 2
	PERF_EVENT_IOC_RESET                = 0x2400 + 3
	PERF_EVENT_IOC_PERIOD               = 0x40080000 | (0x2400 + 4)
	PERF_EVENT_IOC_SET_OUTPUT           = 0x2400 + 5
	PERF_EVENT_IOC_SET_FILTER           = 0x40080000 | (0x2400 + 6)
	PERF_EVENT_IOC_ID                   = 0x80080000 | (0x2400 + 7)
	PERF_EVENT_IOC_SET_BPF              = 0x40040000 | (0x2400 + 8)
	PERF_EVENT_IOC_PAUSE_OUTPUT         = 0x40040000 | (0x2400 + 9)
)
View Source 
const (
	PERF_FLAG_FD_NO_GROUP uintptr = 1 << iota
	PERF_FLAG_FD_OUTPUT
	PERF_FLAG_PID_CGROUP
	PERF_FLAG_FD_CLOEXEC
)
View Source 
const (
	PERF_FORMAT_TOTAL_TIME_ENABLED uint64 = 1 << iota
	PERF_FORMAT_TOTAL_TIME_RUNNING
	PERF_FORMAT_ID
	PERF_FORMAT_GROUP
)
View Source 
const (
	PERF_TYPE_HARDWARE uint32 = iota
	PERF_TYPE_SOFTWARE
	PERF_TYPE_TRACEPOINT
	PERF_TYPE_HW_CACHE
	PERF_TYPE_RAW
	PERF_TYPE_BREAKPOINT
	PERF_TYPE_MAX
)
View Source 
const (
	PERF_COUNT_HW_CPU_CYCLES uint64 = iota
	PERF_COUNT_HW_INSTRUCTIONS
	PERF_COUNT_HW_CACHE_REFERENCES
	PERF_COUNT_HW_CACHE_MISSES
	PERF_COUNT_HW_BRANCH_INSTRUCTIONS
	PERF_COUNT_HW_BRANCH_MISSES
	PERF_COUNT_HW_BUS_CYCLES
	PERF_COUNT_HW_STALLED_CYCLES_FRONTEND
	PERF_COUNT_HW_STALLED_CYCLES_BACKEND
	PERF_COUNT_HW_REF_CPU_CYCLES
	PERF_COUNT_HW_MAX
)
View Source 
const (
	PERF_COUNT_HW_CACHE_L1D uint64 = iota
	PERF_COUNT_HW_CACHE_L1I
	PERF_COUNT_HW_CACHE_LL
	PERF_COUNT_HW_CACHE_DTLB
	PERF_COUNT_HW_CACHE_ITLB
	PERF_COUNT_HW_CACHE_BPU
	PERF_COUNT_HW_CACHE_NODE
	PERF_COUNT_HW_CACHE_MAX
)
View Source 
const (
	PERF_COUNT_HW_CACHE_OP_READ uint64 = iota
	PERF_COUNT_HW_CACHE_OP_WRITE
	PERF_COUNT_HW_CACHE_OP_PREFETCH
	PERF_COUNT_HW_CACHE_OP_MAX
)
View Source 
const (
	PERF_COUNT_HW_CACHE_RESULT_ACCESS uint64 = iota
	PERF_COUNT_HW_CACHE_RESULT_MISS
	PERF_COUNT_HW_CACHE_RESULT_MAX
)
View Source 
const (
	PERF_COUNT_SW_CPU_CLOCK uint64 = iota
	PERF_COUNT_SW_TASK_CLOCK
	PERF_COUNT_SW_PAGE_FAULTS
	PERF_COUNT_SW_CONTEXT_SWITCHES
	PERF_COUNT_SW_CPU_MIGRATIONS
	PERF_COUNT_SW_PAGE_FAULTS_MIN
	PERF_COUNT_SW_PAGE_FAULTS_MAJ
	PERF_COUNT_SW_ALIGNMENT_FAULTS
	PERF_COUNT_SW_EMULATION_FAULTS
	PERF_COUNT_SW_DUMMY
	PERF_COUNT_BPF_OUTPUT
	PERF_COUNT_SW_MAX
)
View Source 
const (
	PERF_RECORD_INVALID uint32 = iota
	PERF_RECORD_MMAP
	PERF_RECORD_LOST
	PERF_RECORD_COMM
	PERF_RECORD_EXIT
	PERF_RECORD_THROTTLE
	PERF_RECORD_UNTHROTTLE
	PERF_RECORD_FORK
	PERF_RECORD_READ
	PERF_RECORD_SAMPLE
	PERF_RECORD_MMAP2
	PERF_RECORD_AUX
	PERF_RECORD_ITRACE_START
	PERF_RECORD_LOST_SAMPLES
	PERF_RECORD_SWITCH
	PERF_RECORD_SWITCH_CPU_WIDE
	PERF_RECORD_MAX
)
View Source 
const (
	PERF_SAMPLE_IP uint64 = 1 << iota
	PERF_SAMPLE_TID
	PERF_SAMPLE_TIME
	PERF_SAMPLE_ADDR
	PERF_SAMPLE_READ
	PERF_SAMPLE_CALLCHAIN
	PERF_SAMPLE_ID
	PERF_SAMPLE_CPU
	PERF_SAMPLE_PERIOD
	PERF_SAMPLE_STREAM_ID
	PERF_SAMPLE_RAW
	PERF_SAMPLE_BRANCH_STACK
	PERF_SAMPLE_REGS_USER
	PERF_SAMPLE_STACK_USER
	PERF_SAMPLE_WEIGHT
	PERF_SAMPLE_DATA_SRC
	PERF_SAMPLE_IDENTIFIER
	PERF_SAMPLE_TRANSACTION
	PERF_SAMPLE_REGS_INTR
	PERF_SAMPLE_MAX
)
View Source 
const (
	PERF_EVENT_IOC_FLAG_GROUP uintptr = 1 << iota
)
View Source 
const (
	PERF_RECORD_MISC_COMM_EXEC uint16 = (1 << 13)
)

Variables

View Source 
var (
	// HaveClockID is true if the system supports the ClockID attribute.
	HaveClockID bool

	// TimeBase is the time at which TimeOffsets were determined.
	TimeBase int64

	// TimeOffsets are the time offsets to use for each CPU.
	TimeOffsets []int64
)
View Source 
var EventTypeNames = map[EventType]string{
	EventTypeTracepoint:    "EventTypeTracepoint",
	EventTypeKprobe:        "EventTypeKprobe",
	EventTypeUprobe:        "EventTypeUprobe",
	EventTypeHardware:      "EventTypeHardware",
	EventTypeSoftware:      "EventTypeSoftware",
	EventTypeHardwareCache: "EventTypeHardwareCache",
	EventTypeRaw:           "EventTypeRaw",
	EventTypeBreakpoint:    "EventTypeBreakpoint",
	EventTypeDynamicPMU:    "EventTypeDynamicPMU",
}

EventTypeNames is a mapping of EventType to a human-readable string that is the name of the symbolic constant.

Functions

This section is empty.

Types

type BranchEntry 

type BranchEntry struct {
	From      uint64
	To        uint64
	Mispred   bool
	Predicted bool
	InTx      bool
	Abort     bool
	Cycles    uint16
}

BranchEntry is a translation of the Linux kernel's struct perf_branch_entry into Go. It may appear in SampleRecord if PERF_SAMPLE_BRANCH_STACK is set.

type CounterEventGroupMember 

type CounterEventGroupMember struct {
	EventType EventType
	Config    uint64
}

CounterEventGroupMember defines a counter event group member at registration time. Each member must have an event type of software, hardware, or hardware cache, as well as a configuration value that specifies what counter information to return.

type CounterEventHandlerFn 

type CounterEventHandlerFn func(uint64, *Sample, []CounterEventValue, uint64, uint64)

CounterEventHandlerFn is the signature of a function to call to handle a counter event sample. The first argument is the event ID of the sample to be handled, the second is the sample to be handled, the third is a map of event counter IDs to values, the fourth is the total time the event has been enabled, and the fifth is the total time the event has been running.

type CounterEventValue 

type CounterEventValue struct {
	EventType EventType
	Config    uint64
	Value     uint64
}

CounterEventValue is a counter value returned from the kernel. The EventType and Config values are what were used to register the counter group member, and Value is the value returned with the sample.

type CounterGroup 

type CounterGroup struct {
	TimeEnabled uint64
	TimeRunning uint64
	Values      []CounterValue
}

CounterGroup represents the read values of a group of counter events

type CounterValue 

type CounterValue struct {
	// Globally unique identifier for this counter event. Only
	// present if PERF_FORMAT_ID was specified.
	ID uint64

	// The counter result
	Value uint64
}

CounterValue resepresents the read value of a counter event

type EventAttr 

type EventAttr struct {
	Type                   uint32
	Size                   uint32
	Config                 uint64
	SamplePeriod           uint64
	SampleFreq             uint64
	SampleType             uint64
	ReadFormat             uint64
	Disabled               bool
	Inherit                bool
	Pinned                 bool
	Exclusive              bool
	ExcludeUser            bool
	ExcludeKernel          bool
	ExcludeHV              bool
	ExcludeIdle            bool
	Mmap                   bool
	Comm                   bool
	Freq                   bool
	InheritStat            bool
	EnableOnExec           bool
	Task                   bool
	Watermark              bool
	PreciseIP              uint8
	MmapData               bool
	SampleIDAll            bool
	ExcludeHost            bool
	ExcludeGuest           bool
	ExcludeCallchainKernel bool
	ExcludeCallchainUser   bool
	Mmap2                  bool
	CommExec               bool
	UseClockID             bool
	ContextSwitch          bool
	WakeupEvents           uint32
	WakeupWatermark        uint32
	BPType                 uint32
	BPAddr                 uint64
	Config1                uint64
	BPLen                  uint64
	Config2                uint64
	BranchSampleType       uint64
	SampleRegsUser         uint64
	SampleStackUser        uint32
	ClockID                int32
	SampleRegsIntr         uint64
	AuxWatermark           uint32
	SampleMaxStack         uint16
	// contains filtered or unexported fields
}

EventAttr is a translation of the Linux kernel's struct perf_event_attr into Go. It provides detailed configuration information for the event being created.

type EventMonitor 

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

EventMonitor is a high-level interface to the Linux kernel's perf_event infrastructure.

func NewEventMonitor 

func NewEventMonitor(options ...EventMonitorOption) (monitor *EventMonitor, err error)

NewEventMonitor creates a new EventMonitor instance in the stopped state. Once an EventMonitor instance is returned from this function, its Close method must be called to clean it up gracefully, even if no events are registered or it is never put into the running state.

func (*EventMonitor) Close 

func (monitor *EventMonitor) Close() error

Close gracefully cleans up an EventMonitor instance. If the EventMonitor is still running when Close is called, it will first be stopped. After Close completes, the EventMonitor instance cannot be reused.

func (*EventMonitor) Disable 

func (monitor *EventMonitor) Disable(eventid uint64)

Disable is used to disable a registered event. The event to disable is specified by its event ID as returned when the event was initially registered with the EventMonitor.

func (*EventMonitor) DisableAll 

func (monitor *EventMonitor) DisableAll()

DisableAll disables all events that are registered with the EventMonitor.

func (*EventMonitor) DisableGroup 

func (monitor *EventMonitor) DisableGroup(groupID int32) error

DisableGroup disables all events for an event group.

func (*EventMonitor) DoesTracepointExist 

func (monitor *EventMonitor) DoesTracepointExist(name string) bool

DoesTracepointExist returns true if the named tracepoint exists on the system; otherwise, it returns false.

func (*EventMonitor) Enable 

func (monitor *EventMonitor) Enable(eventid uint64)

Enable is used to enable a registered event. The event to enable is specified by its event ID as returned when the event was initially registered with the EventMonitor.

func (*EventMonitor) EnableAll 

func (monitor *EventMonitor) EnableAll()

EnableAll enables all events that are registered with the EventMonitor.

func (*EventMonitor) EnableGroup 

func (monitor *EventMonitor) EnableGroup(groupID int32) error

EnableGroup enables all events for an event group.

func (*EventMonitor) NextProbeName 

func (monitor *EventMonitor) NextProbeName(delta uint64) string

NextProbeName is used primarily for unit testing. It returns the next probe name that will be used by either RegisterKprobe or RegisterUprobe. Any delta specified is added to the counter (intended for use by unit testing)

func (*EventMonitor) RegisterCounterEventGroup 

func (monitor *EventMonitor) RegisterCounterEventGroup(
	name string,
	counters []CounterEventGroupMember,
	handlerFn CounterEventHandlerFn,
	lostRecordFn EventMonitorLostRecordFn,
	options ...RegisterEventOption,
) (int32, uint64, error)

RegisterCounterEventGroup registers a performance counter event group.

func (*EventMonitor) RegisterEventGroup 

func (monitor *EventMonitor) RegisterEventGroup(
	name string,
	lostRecordFn EventMonitorLostRecordFn,
) (int32, error)

RegisterEventGroup creates a new event group that can be used for grouping events. If the kernel reports lost records, the function specified here will be called with relevent information.

func (*EventMonitor) RegisterKprobe 

func (monitor *EventMonitor) RegisterKprobe(
	address string,
	onReturn bool,
	output string,
	handlerFn TraceEventHandlerFn,
	groupID int32,
	options ...RegisterEventOption,
) (uint64, error)

RegisterKprobe is used to register a kprobe with an EventMonitor. The kprobe will first be registered with the kernel, and then registered with the EventMonitor. An event ID is returned that is unqiue to the EventMonitor and is to be used to unregister the event. The event ID will also be passed to the EventMonitor's dispatch function.

func (*EventMonitor) RegisterTracepoint 

func (monitor *EventMonitor) RegisterTracepoint(
	name string,
	handlerFn TraceEventHandlerFn,
	groupID int32,
	options ...RegisterEventOption,
) (uint64, error)

RegisterTracepoint is used to register a tracepoint with an EventMonitor. The tracepoint is selected by name and it must exist in the running Linux kernel. An event ID is returned that is unique to the EventMonitor and is to be used to unregister the event. The event ID will also be passed to the EventMonitor's dispatch function.

func (*EventMonitor) RegisterUprobe 

func (monitor *EventMonitor) RegisterUprobe(
	bin string,
	address string,
	onReturn bool,
	output string,
	handlerFn TraceEventHandlerFn,
	groupID int32,
	options ...RegisterEventOption,
) (uint64, error)

RegisterUprobe is used to register a uprobe with an EventMonitor. The uprobe will first be registered with the kernel, and then registered with the EventMonitor. An event ID is returned that is unique to the EventMonitor and is to be used to unregister the event. The event ID will also be passed to the EventMonitor's dispatch function.

func (*EventMonitor) RegisteredEventFields 

func (monitor *EventMonitor) RegisteredEventFields(
	eventID uint64,
) expression.FieldTypeMap

RegisteredEventFields returns the fields that are defined for the specified event identifier.

func (*EventMonitor) RegisteredEventType 

func (monitor *EventMonitor) RegisteredEventType(
	eventID uint64,
) (EventType, bool)

RegisteredEventType returns the type of an event

func (*EventMonitor) ReserveEventID 

func (monitor *EventMonitor) ReserveEventID() uint64

ReserveEventID is used to reserve an event ID.

func (*EventMonitor) Run 

func (monitor *EventMonitor) Run() error

Run puts an EventMonitor into the running state. While an EventMonitor is running, samples will be pulled from event sources, decoded, and dispatched to functions as specified when kprobes, tracepoints, etc. are registered.

func (*EventMonitor) SetFilter 

func (monitor *EventMonitor) SetFilter(
	eventid uint64,
	filter string,
) error

SetFilter is used to set or remove a filter from a registered event.

func (*EventMonitor) Stop 

func (monitor *EventMonitor) Stop(wait bool)

Stop stops a running EventMonitor. If the EventMonitor is not running, this function does nothing. Once an EventMonitor has been stopped, it may be restarted again. Whether Stop waits for the EventMonitor to fully stop is optional, but if the caller does not wait there is no other mechanism by which the caller may learn whether the EventMonitor is stopped.

func (*EventMonitor) UnregisterEvent 

func (monitor *EventMonitor) UnregisterEvent(eventid uint64) error

UnregisterEvent is used to remove a previously registered event from an EventMonitor. The event can be of any type and is specified by the event ID that was returned when the event was initially registered with the EventMonitor.

func (*EventMonitor) UnregisterEventGroup 

func (monitor *EventMonitor) UnregisterEventGroup(groupID int32) error

UnregisterEventGroup removes a registered event group. If there are any events registered with the event group, they will be unregistered as well.

type EventMonitorLostRecordFn 

type EventMonitorLostRecordFn func(uint64, int32, SampleID, uint64)

EventMonitorLostRecordFn is the signature of a function that is called when lost records are reported by the kernel. The first argument is the event ID of the first valid record recorded after a loss of records, the second argument is the SampleID information for the LostRecord, and the third argument is the number of records that were lost.

type EventMonitorOption 

type EventMonitorOption func(*eventMonitorOptions)

EventMonitorOption is used to implement optional arguments for NewEventMonitor. It must be exported, but it is not typically used directly.

func WithCgroup 

func WithCgroup(cgroup string) EventMonitorOption

WithCgroup is used to add a cgroup to the set of sources to monitor.

func WithCgroups 

func WithCgroups(cgroups []string) EventMonitorOption

WithCgroups is used to add a list of cgroups to the set of sources to monitor.

func WithDefaultEventAttr 

func WithDefaultEventAttr(defaultEventAttr *EventAttr) EventMonitorOption

WithDefaultEventAttr is used to set an optional EventAttr struct to be used by default when registering events and no EventAttr is specified as part of the registration.

func WithEventSourceController 

func WithEventSourceController(controller EventSourceController) EventMonitorOption

WithEventSourceController is used to set the event source controller to be used. If left unspecified, the default system event source controller will be used. Any controller specified here will be owned immediately by NewEventMonitor, which primarily means that its Close method will be called if any error occurs while creating the new EventMonitor. If an EventMonitor is created successfully, the event source controller's Close method will not be called until the monitor's Close method is called.

func WithFlags 

func WithFlags(flags uintptr) EventMonitorOption

WithFlags is used to set optional flags when creating a new EventMonitor. The flags are passed to the low-level perf_event_open() system call.

func WithPerfEventDir 

func WithPerfEventDir(dir string) EventMonitorOption

WithPerfEventDir is used to set an optional directory to use for monitoring cgroups. This should only be necessary if the perf_event cgroup fs is not mounted in the usual location.

func WithPid 

func WithPid(pid int) EventMonitorOption

WithPid is used to add a pid to the set of sources to monitor.

func WithPids 

func WithPids(pids []int) EventMonitorOption

WithPids is used to add a list of pids to the set of sources to monitor.

func WithProcFileSystem 

func WithProcFileSystem(procfs proc.FileSystem) EventMonitorOption

WithProcFileSystem is used to set the proc.FileSystem to use. The system default will be used if one is not specified.

func WithRingBufferNumPages 

func WithRingBufferNumPages(numPages int) EventMonitorOption

WithRingBufferNumPages is used to set the size of the ringbuffers used to retrieve samples from the kernel.

func WithTracingDir 

func WithTracingDir(dir string) EventMonitorOption

WithTracingDir is used to set an alternate mountpoint to use for managing tracepoints, kprobes, and uprobes.

type EventSource 

type EventSource interface {
	// Close terminates the event source.
	Close() error

	// Disable disables the event source without terminating it. The event
	// source may be re-enabled. It is not an error to disable an already
	// disabled source.
	Disable() error

	// Enable enables the event source. It is not an error to enable an
	// already enabled source.
	Enable() error

	// SetFilter sets a filter for an event source. Using the empty string
	// for the filter clears the filter.
	SetFilter(filter string) error

	// SourceID returns a unique identifier for the EventSource.
	SourceID() uint64
}

EventSource defines the interface for an event source.

type EventSourceController 

type EventSourceController interface {
	// Close closes the EventSourceController, cleaning up any resources
	// that it may have reserved for itself. The EventSourceController is
	// no longer usable after this function completes.
	Close()

	// NewEventSourceLeader creates a new event source as a group leader.
	// Group leaders may or may not have event sources as children.
	NewEventSourceLeader(attr EventAttr, pid, cpu int, flags uintptr) (EventSourceLeader, error)

	// Wait pauses execution until events become available for processing.
	// A list of source IDs will be returned, one for each EventSourceLeader
	// that is ready for processing. The order is undefined.
	Wait() ([]uint64, error)

	// Wakeup wakes up the controller if it is blocked in a wait state.
	Wakeup()
}

EventSourceController defines the interface with which EventMonitor will obtain event information.

type EventSourceLeader 

type EventSourceLeader interface {
	EventSource

	// NewEventSource creates a new EventSource that is a member of the
	// group that this EventSourceLeader leads.
	NewEventSource(attr EventAttr, flags uintptr) (EventSource, error)

	// Read retrieves the raw data available from the event source. The
	// function will return nil if there is no data availble for reading;
	// otherwise it will return a byte slice that contains the data from
	// the source. The acquireBuffer function will be called to acquire the
	// byte slice to read into. To avoid the creation of tiny, short-lived
	// objects that will put pressure on GC, the acquireBuffer function
	// will return a byte slice and an offset into the byte slice where the
	// data should be written.
	Read(acquireBuffer func(size int) ([]byte, int))
}

EventSourceLeader defines the interface for an event source that is also a group leader.

type EventType 

type EventType int

EventType represents the type of an event (tracepoint, hardware, etc.) 

const (
	// EventTypeInvalid is not a valid event type
	EventTypeInvalid EventType = iota

	// EventTypeTracepoint is a trace event (PERF_TYPE_TRACEPOINT)
	EventTypeTracepoint

	// EventTypeKprobe is a kernel probe
	EventTypeKprobe
	// EventTypeUprobe is a user probe
	EventTypeUprobe

	// EventTypeHardware is a hardware event (PERF_TYPE_HARDWARE)
	EventTypeHardware

	// EventTypeSoftware is a software event (PERF_TYPE_SOFTWARE)
	EventTypeSoftware

	// EventTypeHardwareCache is a hardware cache event (PERF_TYPE_HW_CACHE)
	EventTypeHardwareCache

	// EventTypeRaw is a raw event (PERF_TYPE_RAW)
	EventTypeRaw

	// EventTypeBreakpoint is a breakpoint event (PERF_TYPE_BREAKPOINT)
	EventTypeBreakpoint

	// EventTypeDynamicPMU is a dynamic PMU event
	EventTypeDynamicPMU
)

type RegisterEventOption 

type RegisterEventOption func(*registerEventOptions)

RegisterEventOption is used to implement optional arguments for event registration methods. It must be exported, but it is not typically used directly.

func WithEventAttr 

func WithEventAttr(eventAttr *EventAttr) RegisterEventOption

WithEventAttr is used to register the event with an EventAttr struct instead of using the EventMonitor's default.

func WithEventDisabled 

func WithEventDisabled() RegisterEventOption

WithEventDisabled is used to register the event in a disabled state.

func WithEventEnabled 

func WithEventEnabled() RegisterEventOption

WithEventEnabled is used to register the event in an enabled state.

func WithFilter 

func WithFilter(filter string) RegisterEventOption

WithFilter is used to set a filter for the event.

func WithTracingEventName 

func WithTracingEventName(name string) RegisterEventOption

WithTracingEventName is used to specify the name of a kprobe or uprobe to use for registration instead of an automatically generated one.

type Sample 

type Sample struct {
	Type uint32
	Misc uint16

	SampleID

	// If Type == PERF_RECORD_LOST, this will be the count of lost records
	Lost uint64

	// If Type == PERF_RECORD_SAMPLE, the rest of this will be filled in
	// accordingly
	IP          uint64
	Addr        uint64
	Period      uint64
	V           CounterGroup
	IPs         []uint64
	RawData     []byte
	Branches    []BranchEntry
	UserABI     uint64
	UserRegs    []uint64
	StackData   []uint64
	Weight      uint64
	DataSrc     uint64
	Transaction uint64
	IntrABI     uint64
	IntrRegs    []uint64

	// TraceFormat is primarily used internally to decode RawData on-demand
	// It is exposed publicly to facilitate unit testing.
	TraceFormat TraceEventFormat
}

Sample is the representation of a perf_event sample retrieved from the Linux kernel. It includes the header information, a translation of the sample data, and metadata depending on the flags set in the EventAttr used to enable the event that generated the sample.

func (*Sample) DecodeRawData 

func (sample *Sample) DecodeRawData() (expression.FieldValueMap, error)

DecodeRawData decodes a sample's raw data into a dictionary of field names and values.

func (*Sample) DecodeValue 

func (sample *Sample) DecodeValue(name string) (interface{}, error)

DecodeValue decodes the specified field from a sample's raw data.

func (*Sample) GetBool 

func (sample *Sample) GetBool(name string) (bool, error)

GetBool is present solely to conform to expression.FieldValueGetter. It will always return an error because the kernel does not support a Boolean type.

func (*Sample) GetDouble 

func (sample *Sample) GetDouble(name string) (float64, error)

GetDouble is present solely to conform to expression.FieldValueGetter. It will always return an error because the kernel does not support a floating point type.

func (*Sample) GetSignedInt16 

func (sample *Sample) GetSignedInt16(name string) (int16, error)

GetSignedInt16 returns the signed 16-bit integer value set for the requested field name.

func (*Sample) GetSignedInt32 

func (sample *Sample) GetSignedInt32(name string) (int32, error)

GetSignedInt32 returns the signed 32-bit integer value set for the requested field name.

func (*Sample) GetSignedInt64 

func (sample *Sample) GetSignedInt64(name string) (int64, error)

GetSignedInt64 returns the signed 64-bit integer value set for the requested field name.

func (*Sample) GetSignedInt8 

func (sample *Sample) GetSignedInt8(name string) (int8, error)

GetSignedInt8 returns the signed 8-bit integer value set for the requested field name.

func (*Sample) GetString 

func (sample *Sample) GetString(name string) (string, error)

GetString returns the string value set for the requested field name.

func (*Sample) GetTimestamp 

func (sample *Sample) GetTimestamp(name string) (time.Time, error)

GetTimestamp is present solely to conform to expression.FieldValueGetter. It will always return an error because the kernel does not support a timestamp type.

func (*Sample) GetUnsignedInt16 

func (sample *Sample) GetUnsignedInt16(name string) (uint16, error)

GetUnsignedInt16 returns the unsigned 16-bit integer value set for the requested field name.

func (*Sample) GetUnsignedInt32 

func (sample *Sample) GetUnsignedInt32(name string) (uint32, error)

GetUnsignedInt32 returns the unsigned 32-bit integer value set for the requested field name.

func (*Sample) GetUnsignedInt64 

func (sample *Sample) GetUnsignedInt64(name string) (uint64, error)

GetUnsignedInt64 returns the unsigned 64-bit integer value set for the requested field name.

func (*Sample) GetUnsignedInt8 

func (sample *Sample) GetUnsignedInt8(name string) (uint8, error)

GetUnsignedInt8 returns the unsigned 8-bit integer value set for the requested field name.

type SampleID 

type SampleID struct {
	PID      uint32
	TID      uint32
	Time     uint64
	ID       uint64
	StreamID uint64
	CPU      uint32
}

SampleID is a translation of the structure used by the Linux kernel for all samples when SampleIDAll is set in the EventAttr used for a sample.

type StubEventSource 

type StubEventSource struct {
	CloseCount     int
	DisableCount   int
	EnableCount    int
	SetFilterCount int
	Filter         string
	Enabled        bool
	Closed         bool
	// contains filtered or unexported fields
}

StubEventSource is an event source implementation used as part of StubEventSourceController.

func (*StubEventSource) Close 

func (s *StubEventSource) Close() error

Close terminates the event source.

func (*StubEventSource) Disable 

func (s *StubEventSource) Disable() error

Disable disables the event source without terminating it. The event source may be re-enabled. It is not an error to disable an already disabled source.

func (*StubEventSource) Enable 

func (s *StubEventSource) Enable() error

Enable enables the event source. It is not an error to enable an already enabled source.

func (*StubEventSource) SetFilter 

func (s *StubEventSource) SetFilter(filter string) error

SetFilter sets a filter for an event source. Using the empty string for the filter clears the filter.

func (*StubEventSource) SourceID 

func (s *StubEventSource) SourceID() uint64

SourceID returns a unique identifier for the EventSource.

type StubEventSourceController 

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

StubEventSourceController is a stub implementation of EventSourceController intended primarily for use in testing EventMonitor.

func NewStubEventSourceController 

func NewStubEventSourceController() *StubEventSourceController

NewStubEventSourceController creates a new StubEventSourceController and initializes it for use.

func (*StubEventSourceController) Close 

func (c *StubEventSourceController) Close()

Close closes the EventSourceController, cleaning up any resources that it may have reserved for itself. The EventSourceController is no longer usable after this function completes.

func (*StubEventSourceController) NewEventSourceLeader 

func (c *StubEventSourceController) NewEventSourceLeader(
	attr EventAttr,
	pid, cpu int,
	flags uintptr,
) (EventSourceLeader, error)

NewEventSourceLeader creates a new event source as a group leader. Group leaders may or may not have event sources as children.

func (*StubEventSourceController) Wait 

func (c *StubEventSourceController) Wait() ([]uint64, error)

Wait pauses execution until events become available for processing. A list of cookies will be returned, one for each EventSourceLeader that is ready for processing. The order is undefined.

func (*StubEventSourceController) Wakeup 

func (c *StubEventSourceController) Wakeup()

Wakeup wakes up the controller if it is blocked in a wait state.

type StubEventSourceLeader 

type StubEventSourceLeader struct {
	StubEventSource
	// contains filtered or unexported fields
}

StubEventSourceLeader is an event source implementation used as part of StubEventSourceController.

func (*StubEventSourceLeader) Close 

func (s *StubEventSourceLeader) Close() error

Close terminates the event source.

func (*StubEventSourceLeader) NewEventSource 

func (s *StubEventSourceLeader) NewEventSource(
	attr EventAttr,
	flags uintptr,
) (EventSource, error)

NewEventSource creates a new EventSource that is a member of the group that this EventSourceLeader leads.

func (*StubEventSourceLeader) Read 

func (s *StubEventSourceLeader) Read(
	acquireBuffer func(size int) ([]byte, int),
)

Read retrieves the raw data available from the event source. The function will return nil if there is no data availble for reading; otherwise it will return a byte slice that contains the data from the source. The acquireBuffer function will be called to acquire the byte slice to read into. To avoid the creation of tiny, short-lived objects that will put pressure on GC, the acquireBuffer function will return a byte slice and an offset into the byte slice where the data should be written.

type TimedEvent 

type TimedEvent interface {
	// Close cleans up any resources used by the TimedEvent. The TimedEvent
	// becomes unusable after it has been closed.
	Close()

	// Signal signals a TimedEvent. The signal remains set even if there is
	// not a waiter. The next wait will wake immediately. This behavior is
	// needed because we cannot work with a mutex to avoid race conditions.
	// Normally we would lock the mutex, signal, then unlock the mutex.
	Signal()

	// Wait for the TimedEvent to be signaled or wait for the specified
	// timeout to elapse, whichever happens first. A negative duration
	// waits forever. A duration of 0 times out immediately. The return is
	// true if the Wait returned because the TimedEvent was signalled;
	// otherwise, it returns false to indicate a timeout occurred. The
	// event may already be signalled on entry, in which case the Wait will
	// return immediately. This behavior is needed because we cannot work
	// with a mutex to avoid race conditions. Normally the mutex would be
	// locked when Wait is called, and Wait would atomically unlock the
	// mutex while waiting, locking it again once woken up.
	Wait(timeout time.Duration) bool
}

TimedEvent defines the interface for an object implementing a dual signaling mechanism: explicit wake-up or timeout. This is necessary because the Go runtime does not support anything of the kind, instead forcing the use of channels to achieve the same effect. Unfortunately this method also requires several new object allocations every time it is employed or it gets overly complicated. This interface exists to abstract away the ugliness and allow alternate implementations that may be better but not available on all platforms. The actual desired behavior is exactly that of a timed wait on a cond with a mutex (the POSIX version would be pthread_cond_timedwait). Since we cannot work atomically with a mutex and wait, we have to employ alternate behavior as described for each of the interfaces methods.

type TraceEventField 

type TraceEventField struct {
	// FieldName is the name of the field.
	FieldName string
	// TypeName is the name of the field's type.
	TypeName string
	// Offset is the byte offset at which the field data begins.
	Offset int
	// Size is the number of bytes that make up the entirety of the field's
	// data.
	Size int
	// IsSigned is true if the field is signed; otherwise, it is false.
	IsSigned bool
	// DataType is the data type of this field.
	DataType expression.ValueType
	// DataTypeSize is the size of the data type. For arrays, this is the
	// size of each element. For scalars, this is the same as Size.
	DataTypeSize int
	// DataLocSize is the size of data location information, if present.
	// This is used for strings and dynamically sized arrays.
	DataLocSize int
	// If non-zero, this specifies the length of a fixed-size array, with
	// data present inline rather than using DataLocSize.
	ArraySize int
}

TraceEventField represents a single field in a TraceEventFormat.

func (*TraceEventField) DecodeRawData 

func (field *TraceEventField) DecodeRawData(rawData []byte) (interface{}, error)

DecodeRawData decodes a field from raw data.

func (*TraceEventField) DecodeSignedInt16 

func (field *TraceEventField) DecodeSignedInt16(rawData []byte) (int16, error)

DecodeSignedInt16 decodes a signed 16-bit integer field from raw data.

func (*TraceEventField) DecodeSignedInt32 

func (field *TraceEventField) DecodeSignedInt32(rawData []byte) (int32, error)

DecodeSignedInt32 decodes a signed 32-bit integer field from raw data.

func (*TraceEventField) DecodeSignedInt64 

func (field *TraceEventField) DecodeSignedInt64(rawData []byte) (int64, error)

DecodeSignedInt64 decodes a signed 64-bit integer field from raw data.

func (*TraceEventField) DecodeSignedInt8 

func (field *TraceEventField) DecodeSignedInt8(rawData []byte) (int8, error)

DecodeSignedInt8 decodes a signed 8-bit integer field from raw data.

func (*TraceEventField) DecodeString 

func (field *TraceEventField) DecodeString(rawData []byte) (string, error)

DecodeString decodes a string field from raw data.

func (*TraceEventField) DecodeUnsignedInt16 

func (field *TraceEventField) DecodeUnsignedInt16(rawData []byte) (uint16, error)

DecodeUnsignedInt16 decodes an unsigned 16-bit integer field from raw data.

func (*TraceEventField) DecodeUnsignedInt32 

func (field *TraceEventField) DecodeUnsignedInt32(rawData []byte) (uint32, error)

DecodeUnsignedInt32 decodes an unsigned 32-bit integer field from raw data.

func (*TraceEventField) DecodeUnsignedInt64 

func (field *TraceEventField) DecodeUnsignedInt64(rawData []byte) (uint64, error)

DecodeUnsignedInt64 decodes an unsigned 64-bit integer field from raw data.

func (*TraceEventField) DecodeUnsignedInt8 

func (field *TraceEventField) DecodeUnsignedInt8(rawData []byte) (uint8, error)

DecodeUnsignedInt8 decodes an unsigned 8-bit integer field from raw data.

type TraceEventFormat 

type TraceEventFormat map[string]TraceEventField

TraceEventFormat represents the format of a kernel tracing event.

func (TraceEventFormat) DecodeRawData 

func (f TraceEventFormat) DecodeRawData(rawData []byte) (expression.FieldValueMap, error)

DecodeRawData decodes a buffer of raw bytes according to the kernel defined format that has been parsed from the tracing filesystem.

type TraceEventHandlerFn 

type TraceEventHandlerFn func(uint64, *Sample)

TraceEventHandlerFn is the signature of a function to call to handle a sample. The first argument is the event ID of the event source that produced the sample. The second argument is the sample, and the final argument is the parsed sample data.

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.