Expand description
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
sourceimpl<T: DerefMut<Target = Map>> PerfEventArray<T>
impl<T: DerefMut<Target = Map>> PerfEventArray<T>
sourcepub fn open(
&mut self,
index: u32,
page_count: Option<usize>
) -> Result<PerfEventArrayBuffer<T>, PerfBufferError>
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
Auto Trait Implementations
impl<T> RefUnwindSafe for PerfEventArray<T> where
T: RefUnwindSafe,
impl<T> Send for PerfEventArray<T> where
T: Send + Sync,
impl<T> Sync for PerfEventArray<T> where
T: Send + Sync,
impl<T> Unpin for PerfEventArray<T>
impl<T> UnwindSafe for PerfEventArray<T> where
T: RefUnwindSafe,
Blanket Implementations
sourceimpl<T> BorrowMut<T> for T where
T: ?Sized,
impl<T> BorrowMut<T> for T where
T: ?Sized,
const: unstable · sourcefn borrow_mut(&mut self) -> &mut T
fn borrow_mut(&mut self) -> &mut T
Mutably borrows from an owned value. Read more