Struct PerfEventArray 

pub struct PerfEventArray<T> { /* 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
• drain events with PerfEventArrayBuffer::for_each (or fold/try_fold)

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;

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

// 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().map_err(|(_, error)| error)? {
    // this perf buffer will receive events generated on the CPU with id cpu_id
    perf_buffers.push(perf_array.open(cpu_id, None)?);
}

// poll the buffers to know when they have queued events
let poll = poll_buffers(perf_buffers);
loop {
    for perf_buf in poll.poll_readable() {
        perf_buf.for_each(|event| match event {
            PerfEvent::Sample { head, tail } => {
                // process the sample bytes (`tail` is empty unless the sample wraps)
            }
            PerfEvent::Lost { count } => {
                // record the dropped-events counter
            }
        });
    }
}

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.

Implementations

impl<T: Borrow<MapData>> PerfEventArray<T>

pub fn pin<P: AsRef<Path>>(&self, path: P) -> Result<(), PinError>

Pins the map to a BPF filesystem.

When a map is pinned it will remain loaded until the corresponding file is deleted. All parent directories in the given path must already exist.

impl<T: BorrowMut<MapData>> 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<'a> TryFrom<&'a Map> for PerfEventArray<&'a MapData>

type Error = MapError

The type returned in the event of a conversion error.

fn try_from(map: &'a Map) -> Result<Self, Self::Error>

Performs the conversion.

impl<'a> TryFrom<&'a mut Map> for PerfEventArray<&'a mut MapData>

type Error = MapError

The type returned in the event of a conversion error.

fn try_from(map: &'a mut Map) -> Result<Self, Self::Error>

Performs the conversion.

impl TryFrom<Map> for PerfEventArray<MapData>

type Error = MapError

The type returned in the event of a conversion error.

fn try_from(map: Map) -> Result<Self, Self::Error>

Performs the conversion.