package perf

import "github.com/cilium/ebpf/perf"

Package perf allows interacting with Linux perf_events.

BPF allows submitting custom perf_events to a ring-buffer set up by userspace. This is very useful to push things like packet samples from BPF to a daemon running in user space.

Index ¶

• Variables
• func IsUnknownEvent(err error) bool
• type Reader
• func NewReader(array *ebpf.Map, perCPUBuffer int) (*Reader, error)
• func NewReaderWithOptions(array *ebpf.Map, perCPUBuffer int, opts ReaderOptions) (pr *Reader, err error)
• func (pr *Reader) Close() error
• func (pr *Reader) Pause() error
• func (pr *Reader) Read() (Record, error)
• func (pr *Reader) Resume() error
• type ReaderOptions
• type Record

Examples ¶

• Reader

Variables ¶

var (
	ErrClosed = os.ErrClosed
)

Functions ¶

func IsUnknownEvent ¶

func IsUnknownEvent(err error) bool

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

Types ¶

type Reader ¶

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

Reader allows reading bpf_perf_event_output from user space.

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);
 }

{
	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(make([]byte, 14))
	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)
}

func NewReader ¶

func NewReader(array *ebpf.Map, perCPUBuffer int) (*Reader, error)

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 ¶

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

NewReaderWithOptions creates a new reader with the given options.

func (*Reader) Close ¶

func (pr *Reader) Close() error

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.

func (*Reader) Pause ¶

func (pr *Reader) Pause() 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.

func (*Reader) Read ¶

func (pr *Reader) Read() (Record, error)

Read the next record from the perf ring buffer.

The function 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 function.

func (*Reader) Resume ¶

func (pr *Reader) Resume() error

Resume allows this perf reader to emit notifications.

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

type ReaderOptions ¶

type ReaderOptions struct {
	// The number of written bytes required in any per CPU buffer before
	// Read will process data. Must be smaller than PerCPUBuffer.
	// The default is to start processing as soon as data is available.
	Watermark int
}

ReaderOptions control the behaviour of the user space reader.

type Record ¶

type Record struct {
	// The CPU this record was generated on.
	CPU int

	// The data submitted via bpf_perf_event_output.
	// Due to a kernel bug, this can contain between 0 and 7 bytes of trailing
	// garbage from the ring depending on the input sample's length.
	RawSample []byte

	// The number of samples which could not be output, since
	// the ring buffer was full.
	LostSamples uint64
}

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

Source Files ¶

doc.go reader.go ring.go