Module perf_event::hooks

Intercepting perf-event system calls, for testing and logging.

Note: this module is only available when the "hooks" feature is enabled.

Many performance counters’ behavior is inherently non-deterministic, making it difficult to write tests for code that uses the perf_event crate. There may be no way to reliably provoke the Linux kernel into exhibiting the behavior you want to test against. Or you may want to test functionality like whole-system profiling, which requires elevated privileges that one would prefer to avoid granting to tests.

This module lets you interpose your own implementation of all the system calls and ioctls that perf_event uses, granting you complete control over perf_event’s interactions with the outside world. You can verify that the system calls receive the parameters you expect, and provide whatever sorts of interesting responses you need.

There are three main pieces:

• The Hooks trait has a method for every system call and ioctl that the perf_event crate uses.

• The set_thread_hooks function lets you provide a Box<dyn Hooks> trait object whose methods the calling thread will use for all subsequent perf_event operations.

• The clear_thread_hooks function restores the thread’s original state, so that subsequent perf_event operations use the real Linux system calls.

This functionality is too low-level for direct use in tests, but it does provide the means with which one can build more ergonomic test harnesses.

Stability

Using set_thread_hooks, you can observe the exact sequence of system operations that the perf_event crate performs to carry out requests from the user. Even if the interface remains the same, the implementation of those requests can change without notice, possibly causing a Hooks implementation to see a different set of calls.

The perf_event crate will not treat such implementation changes as breaking changes for semver purposes, despite the fact that they may break code using this module’s functionality.

Modules

sys

Wrapper around the perf_event_open_sys crate that supports intercepting system calls and returning simulated results, for testing.

Structs

RealHooks

An implementation of the Hooks trait in terms of the real Linux system calls.

Traits

Hooks

A trait with a method for every system call and ioctl used by this crate.

Functions

clear_thread_hooks^⚠

Direct all perf-event system calls on this thread to the real system calls.

set_thread_hooks^⚠

Direct all perf-event system calls on this thread to hooks.