perf package - github.com/cilium/ebpf/perf - Go Packages (original) (raw)

Package perf allows reading from BPF perf event arrays.

A perf event array contains multiple perf event ringbuffers which can be used to exchange sample like data with user space.

This section is empty.

IsUnknownEvent returns true if the error occurred because an unknown event was submitted to the perf event ring.

Reader allows reading bpf_perf_event_output from user space.

ExampleReader submits a perf event using BPF, and then reads it in user space.

The BPF will look something like this:

struct map events __section("maps") = { .type = BPF_MAP_TYPE_PERF_EVENT_ARRAY, };

__section("xdp") int output_single(void *ctx) { unsigned char buf[] = { 1, 2, 3, 4, 5 };

return perf_event_output(ctx, &events, BPF_F_CURRENT_CPU, &buf[0], 5); }

Also see BPF_F_CTXLEN_MASK if you want to sample packet data from SKB or XDP programs.

prog, events := bpfPerfEventOutputProgram() defer prog.Close() defer events.Close()

rd, err := NewReader(events, 4096) if err != nil { panic(err) } defer rd.Close()

// Writes out a sample with content 1,2,3,4,4 ret, _, err := prog.Test(internal.EmptyBPFContext) if err != nil || ret != 0 { panic("Can't write sample") }

record, err := rd.Read() if err != nil { panic(err) }

// Data is padded with 0 for alignment fmt.Println("Sample:", record.RawSample)

NewReader creates a new reader with default options.

array must be a PerfEventArray. perCPUBuffer gives the size of the per CPU buffer in bytes. It is rounded up to the nearest multiple of the current page size.

func NewReaderWithOptions(array *ebpf.Map, perCPUBuffer int, opts ReaderOptions) (pr *Reader, err error)

NewReaderWithOptions creates a new reader with the given options.

func (pr *Reader) BufferSize() int

BufferSize is the size in bytes of each per-CPU buffer

Close frees resources used by the reader.

It interrupts calls to Read.

Calls to perf_event_output from eBPF programs will return ENOENT after calling this method.

Flush unblocks Read/ReadInto and successive Read/ReadInto calls will return pending samples at this point, until you receive a ErrFlushed error.

Pause stops all notifications from this Reader.

While the Reader is paused, any attempts to write to the event buffer from BPF programs will return -ENOENT.

Subsequent calls to Read will block until a call to Resume.

Read the next record from the perf ring buffer.

The method blocks until there are at least Watermark bytes in one of the per CPU buffers. Records from buffers below the Watermark are not returned.

Records can contain between 0 and 7 bytes of trailing garbage from the ring depending on the input sample's length.

Calling [Close] interrupts the method with os.ErrClosed. Calling [Flush] makes it return all records currently in the ring buffer, followed by ErrFlushed.

Returns os.ErrDeadlineExceeded if a deadline was set and after all records have been read from the ring.

See Reader.ReadInto for a more efficient version of this method.

func (pr *Reader) ReadInto(rec *Record) error

ReadInto is like Reader.Read except that it allows reusing Record and associated buffers.

ReadRecord allows reducing memory allocations.

prog, events := bpfPerfEventOutputProgram() defer prog.Close() defer events.Close()

rd, err := NewReader(events, 4096) if err != nil { panic(err) } defer rd.Close()

for i := 0; i < 2; i++ { // Write out two samples ret, _, err := prog.Test(internal.EmptyBPFContext) if err != nil || ret != 0 { panic("Can't write sample") } }

var rec Record for i := 0; i < 2; i++ { if err := rd.ReadInto(&rec); err != nil { panic(err) }

fmt.Println("Sample:", rec.RawSample[:5])

}

Resume allows this perf reader to emit notifications.

Subsequent calls to Read will block until the next event notification.

SetDeadline controls how long Read and ReadInto will block waiting for samples.

Passing a zero time.Time will remove the deadline. Passing a deadline in the past will prevent the reader from blocking if there are no records to be read.

type ReaderOptions struct {

WakeupEvents [int](/builtin#int)


Watermark [int](/builtin#int)


Overwritable [bool](/builtin#bool)

}

ReaderOptions control the behaviour of the user space reader.

type Record struct {

CPU [int](/builtin#int)


RawSample [][byte](/builtin#byte)


LostSamples [uint64](/builtin#uint64)


Remaining [int](/builtin#int)

}

Record contains either a sample or a counter of the number of lost samples.