Documentation
¶
Overview ¶
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 ¶
Examples ¶
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
func IsUnknownEvent ¶
IsUnknownEvent returns true if the error occured 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.
Example ¶
ExamplePerfReader 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(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)
Output:
func NewReader ¶
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 ¶
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 ¶
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.
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.
// They are padded with 0 to have a 64-bit alignment.
// If you are using variable length samples you need to take
// this into account.
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