README
¶
perfevents/go
This is the implementation of perfevents package in golang.
Standalone Installation and Usage
perfevents provides an API and a library which can be used by a go application to profile its components.
To use this package inside your go application, use :
import "github.com/opentracing-contrib/perfevents/go"
To open a list of events :
err, evs, pds := perfevents.InitOpenEventsEnableSelf("cpu-cycles,cache-misses,instructions")
This creates 3 event descriptors pds for cpu-cycles,
cache-misses and instructions and enables them, so they
start counting.
At any point in time, we can read the event values :
err, evs = perfevents.EventsRead(pds)
After we are done monitoring, just close out the events :
err, evs = perfevents.EventsDisableClose(pds)
That's it!
Usage with OpenTracing
OpenTracing is a vendor neutral open standard for distributed tracing, which basically means, it provides standard and vendor-neutral APIs for popular platforms, i.e., popular tracing backends implement the OpenTracing API. More on OpenTracing : http://opentracing.io/documentation/.
perfevents can be used with the popular tracing implementations like Zipkin and Jaeger via the go-observer interface.
Usage with Zipkin
In the application where zipkin is initialized, a new perfevents observer must be created. This observer is then assigned to zipkin.
First import the perfevents/go package:
import perfevents "github.com/opentracing-contrib/perfevents/go"
Initialize a perfevents observer:
observer := perfevents.NewObserver()
And then, pass this new observer as part of initialization of zipkin:
tracer, _ := zipkin.NewTracer(..., zipkin.WithObserver(observer))
Now, to start a span with metrics like cache-misses and cycles :
sp := tracer.StartSpan("name", opentracing.Tag{"perfevents", "cpu-cycles,cache-misses"})
With this, the results can be seen in zipkin's UI.
Supported Events
For now, 7 generic hardware events are supported :
- cpu-cycles
- instructions
- cache-references
- cache-misses
- branch-instructions
- branch-misses
- bus-cycles
Supported Tracers
perfevents is supported with distributed tracers which:
- is OpenTracing compliant and,
- provide the go-observer interface.
Right now, the above conditions are satisfied by Zipkin and Jaeger, with jaeger satisfying the second condition indirectly.
TODOs
- Support the hardware cache events.
- Support the dynamic events exported by the kernel.
Documentation
¶
Index ¶
- Constants
- Variables
- func EventsDisableClose(eventsInfo []PerfEventInfo) error
- func EventsRead(eventsInfo []PerfEventInfo) error
- func FormatDataToString(pi PerfEventInfo) string
- type EventConfigType
- type Observer
- type PerfEventAttr
- type PerfEventInfo
- func (event *PerfEventInfo) DisableClose() error
- func (event *PerfEventInfo) DisableEvent() error
- func (event *PerfEventInfo) EnableEvent() error
- func (event *PerfEventInfo) FetchPerfEventAttr(eventName string) (error, PerfEventAttr)
- func (event *PerfEventInfo) InitIOCOps() error
- func (event *PerfEventInfo) InitOpenEventEnable(eventName string, pid int, cpu int, group_fd int, flags uint64) error
- func (event *PerfEventInfo) InitOpenEventEnableSelf(eventName string) error
- func (event *PerfEventInfo) OpenEvent(eventAttr PerfEventAttr, pid int, cpu int, group_fd int, flags uint64) error
- func (event *PerfEventInfo) ReadEvent() error
- func (event *PerfEventInfo) ResetEvent() error
- type PerfIOCOps
- type SpanObserver
Constants ¶
const ( DISABLED = 0 // Starts from bit value 0 INHERIT = 1 PINNED = 2 EXCLUSIVE = 3 EXCLUDE_USER = 4 EXCLUDE_KERNEL = 5 EXCLUDE_HV = 6 EXCLUDE_IDLE = 7 MMAP = 8 COMM = 9 FREQ = 10 INHERIT_STAT = 11 ENABLE_ON_EXEC = 12 TASK = 13 WATERMARK = 14 PRECISE_IP1 = 15 PRECISE_IP2 = 16 MMAP_DATA = 17 SAMPLE_ID_ALL = 18 EXCLUDE_HOST = 19 EXCLUDE_GUEST = 20 EXCLUDE_CALLCHAIN_KERNEL = 21 EXCLUDE_CALLCHAIN_USER = 22 MMAP2 = 23 COMM_EXEC = 24 USE_CLOCKID = 25 CONTEXT_SWITCH = 26 RESERVED_1 = 27 )
Bit fields for the PerfEventAttr.properties value derived from linux/perf_event.h Each of these bits specify how do we want to start our counter.
const ( PERF_TYPE_HARDWARE = 0 PERF_TYPE_SOFTWARE = 1 )
PMU hardware type definitions (from linux/perf_event.h) Only HARDWARE type is supported as of now.
const ( PERF_HW_CPU_CYCLES = 0 PERF_HW_INSTRUCTIONS = 1 PERF_HW_CACHE_REF = 2 PERF_HW_CACHE_MISSES = 3 PERF_HW_BRANCH_INSTRUCTIONS = 4 PERF_HW_BRANCH_MISSES = 5 PERF_HW_BUS_CYCLES = 6 )
List of generic events supported (from linux/perf_event.h) All of these events belong to HARDWARE type events.
const ( PERF_IOC_RESET_X86 = 0x2403 PERF_IOC_ENABLE_X86 = 0x2400 PERF_IOC_DISABLE_X86 = 0x2401 )
Perf IOCTL operations for x86
const ( PERF_IOC_RESET_PPC = 0x20002403 PERF_IOC_ENABLE_PPC = 0x20002400 PERF_IOC_DISABLE_PPC = 0x20002401 )
Perf IOCTL operations for powerpc
Variables ¶
var PerfCloseError = errors.New("error in closing event")
var PerfFdError = errors.New("incorrect file descriptor for event")
var PerfIOCError = errors.New("error in IOCTL call")
var PerfOpenError = errors.New("error in opening event")
var PerfReadError = errors.New("error in reading event data")
var PerfTooManyEvents = errors.New("too many events requested")
var PerfUnsupportedEvent = errors.New("event(s) not supported")
Functions ¶
func EventsDisableClose ¶
func EventsDisableClose(eventsInfo []PerfEventInfo) error
EventsDisableClose : Disable and close all the events in the slice "eventsInfo'
func EventsRead ¶
func EventsRead(eventsInfo []PerfEventInfo) error
EventsRead : Read the event count for a slice of event descriptors in "eventsInfo'
func FormatDataToString ¶
func FormatDataToString(pi PerfEventInfo) string
FormatDataToString converts the data for an event to string
Types ¶
type EventConfigType ¶
type EventConfigType struct {
// contains filtered or unexported fields
}
EventConfigType : The configuration struct for an event
type Observer ¶
type Observer struct{}
TODO: Add a member to keep the list of all available events, which is initialized when NewObserver() is called.
func (*Observer) OnStartSpan ¶
func (o *Observer) OnStartSpan(sp opentracing.Span, operationName string, options opentracing.StartSpanOptions) (otobserver.SpanObserver, bool)
OnStartSpan creates a new Observer for the span
type PerfEventAttr ¶
type PerfEventAttr struct {
// contains filtered or unexported fields
}
PerfEventAttr structure is derived from linux/perf_event.h This struct defines various attributes for a perf event. This is what is set and sent to the linux kernel to create an event.
Note : For the unions, only one member has been taken, viz. sample_period, wakeup_events, config1 and config2 are the members of a union. There are two members in each of the mentioned unions and both of them have the same size in all of the unions.
type PerfEventInfo ¶
type PerfEventInfo struct {
EventName string
Fd int
Data uint64
IOCOps PerfIOCOps
}
PerfEventInfo holds the file descriptor for a perf event. EventName : name of the perf event Fd : File descriptor opened by the perf_event_open syscall. Data : Contains the event data after performing a read on Fd.
func InitOpenEventsEnableSelf ¶
func InitOpenEventsEnableSelf(events string) (error, []string, []PerfEventInfo)
InitOpenEventsEnableSelf opens, enables an event list provided in "events" string. "events" is a comma separated list of supported events. In case of an error, where it couldn't create some or all of the required events in "events", it sends the error and the error'ed events along with the events which it managed to create.
func (*PerfEventInfo) DisableClose ¶
func (event *PerfEventInfo) DisableClose() error
DisableClose disables the event and then closes it.
func (*PerfEventInfo) DisableEvent ¶
func (event *PerfEventInfo) DisableEvent() error
DisableEvent disables an event
func (*PerfEventInfo) EnableEvent ¶
func (event *PerfEventInfo) EnableEvent() error
EnableEvent enables an event
func (*PerfEventInfo) FetchPerfEventAttr ¶
func (event *PerfEventInfo) FetchPerfEventAttr(eventName string) (error, PerfEventAttr)
FetchPerfEventAttr is the same as that of the independent one, just to maintain consistency, this method is defined
func (*PerfEventInfo) InitIOCOps ¶
func (event *PerfEventInfo) InitIOCOps() error
InitIOCOps initializes the Perf IOCTL functions respective to the underlying architecture
func (*PerfEventInfo) InitOpenEventEnable ¶
func (event *PerfEventInfo) InitOpenEventEnable(eventName string, pid int, cpu int, group_fd int, flags uint64) error
InitOpenEventEnable fetches the perf event attributes for event "string", opens the event, resets and then enables the event.
func (*PerfEventInfo) InitOpenEventEnableSelf ¶
func (event *PerfEventInfo) InitOpenEventEnableSelf(eventName string) error
InitOpenEventEnableSelf opens, enables an event for self process
func (*PerfEventInfo) OpenEvent ¶
func (event *PerfEventInfo) OpenEvent(eventAttr PerfEventAttr, pid int, cpu int, group_fd int, flags uint64) error
OpenEvent opens an event
func (*PerfEventInfo) ReadEvent ¶
func (event *PerfEventInfo) ReadEvent() error
ReadEvent reads the event count
func (*PerfEventInfo) ResetEvent ¶
func (event *PerfEventInfo) ResetEvent() error
ResetEvent resets an event
type PerfIOCOps ¶
type PerfIOCOps struct {
// contains filtered or unexported fields
}
PerfIOCOps stores the correct IOC operations respective to the underlying architecture.
type SpanObserver ¶
type SpanObserver struct {
EventDescs []PerfEventInfo
// contains filtered or unexported fields
}
SpanObserver collects perfevent metrics
func NewSpanObserver ¶
func NewSpanObserver(s opentracing.Span, opts opentracing.StartSpanOptions) (*SpanObserver, bool)
NewSpanObserver creates a new SpanObserver that can emit perfevent metrics
func (*SpanObserver) OnFinish ¶
func (so *SpanObserver) OnFinish(options opentracing.FinishOptions)
func (*SpanObserver) OnSetOperationName ¶
func (so *SpanObserver) OnSetOperationName(operationName string)
func (*SpanObserver) OnSetTag ¶
func (so *SpanObserver) OnSetTag(key string, value interface{})
Source Files