Struct aya::maps::perf::PerfEventArray

pub struct PerfEventArray<T: DerefMut<Target = Map>> { /* private fields */ }

A map that can be used to receive events from eBPF programs using the linux perf API.

Each element of a PerfEventArray is a separate PerfEventArrayBuffer which can be used to receive events sent by eBPF programs that use bpf_perf_event_output().

To receive events you need to:

• call PerfEventArray::open
• poll the returned PerfEventArrayBuffer to be notified when events are inserted in the buffer
• call PerfEventArrayBuffer::read_events to read the events

Minimum kernel version

The minimum kernel version required to use this feature is 4.3.

Examples

A common way to use a perf array is to have one perf buffer for each available CPU:

use aya::maps::PerfEventArray;
use aya::util::online_cpus;
use std::convert::{TryFrom, TryInto};
use bytes::BytesMut;

let mut perf_array = PerfEventArray::try_from(bpf.map_mut("EVENTS")?)?;

// eBPF programs are going to write to the EVENTS perf array, using the id of the CPU they're
// running on as the array index.
let mut perf_buffers = Vec::new();
for cpu_id in online_cpus()? {
    // this perf buffer will receive events generated on the CPU with id cpu_id
    perf_buffers.push(perf_array.open(cpu_id, None)?);
}

let mut out_bufs = [BytesMut::with_capacity(1024)];

// poll the buffers to know when they have queued events
let poll = poll_buffers(perf_buffers);
loop {
    for read_buf in poll.poll_readable() {
        read_buf.read_events(&mut out_bufs)?;
        // process out_bufs
    }
}

Polling and avoiding lost events

In the example above the implementation of poll_buffers() and poll.poll_readable() is not given. PerfEventArrayBuffer implements the AsRawFd trait, so you can implement polling using any crate that can poll file descriptors, like epoll, mio etc.

Perf buffers are internally implemented as ring buffers. If your eBPF programs produce large amounts of data, in order not to lose events you might want to process each PerfEventArrayBuffer on a different thread.

Async

If you are using tokio or async-std, you should use AsyncPerfEventArray which efficiently integrates with those and provides a nicer Future based API.

Implementations

impl<T: DerefMut<Target = Map>> PerfEventArray<T>

pub fn open(
    &mut self,
    index: u32,
    page_count: Option<usize>
) -> Result<PerfEventArrayBuffer<T>, PerfBufferError>

Opens the perf buffer at the given index.

The returned buffer will receive all the events eBPF programs send at the given index.

Trait Implementations

impl TryFrom<MapRefMut> for PerfEventArray<MapRefMut>

type Error = MapError

The type returned in the event of a conversion error.

fn try_from(a: MapRefMut) -> Result<PerfEventArray<MapRefMut>, MapError>

Performs the conversion.