EFHS

  ______ ______ _    _  _____ 
 |  ____|  ____| |  | |/ ____|
 | |__  | |__  | |__| | (___  
 |  __| |  __| |  __  |\___ \ 
 | |____| |    | |  | |____) |
 |______|_|    |_|  |_|_____/ 
                               
  eBPF Filesystem Health Sensor

Overview

EFHS is a small eBPF tool to measure block I/O latency and spot drive performance spikes. It uses libbpf and CO-RE to hook into the kernel block layer safely.

• MVP Goals: Track I/O latency (issue to completion), show p50/p95/p99 percentiles, and test it against simulated slow drives (null_blk/dm-delay) using fio.
• Non-Goals: I am not targeting hardware RAID, complex GUIs, or process tracking for the initial version.

Architecture

The tool has two main parts:

• Kernel (src/ebpf/): Hooks into block_rq_issue and block_rq_complete. It saves the start time of an I/O request in a BPF Hash Map using the struct request * pointer as the key, then calculates the duration on completion.
• Userspace (src/userspace/): Loads the BPF program, reads the timestamps via a BPF Ring Buffer, and prints the metrics.

EFHS
├── Makefile
├── README.md
├── src/
│   ├── ebpf/           # sensor.bpf.c (eBPF C code)
│   ├── userspace/      # main.c (Loader and dashboard)
│   └── shared/         # common.h (Shared structs)
├── include/
├── docs/
└── tests/              # Test scripts and virtual disk setup

Current Status & Roadmap

• Phase 1: The Skeleton - COMPLETED
  • Set up standalone libbpf-bootstrap project.
  • Hook into block_rq_issue and verify events show up.
  • Move data tracking from trace_pipe to a BPF Ring Buffer.
  • Calculate basic latency delta (completion time - issue time).

Phase 2: The Latency Engine & Virtual Lab (Current Phase)

• Implement latency threshold flagging (e.g., mark requests exceeding 100ms as degraded).
• Build dm-delay lab script to simulate bad sectors and drive stalls.
• Add basic latency aggregation (tracking min/max/average and histogram buckets).
• Export structured metrics/events for external consumers (JSON/CLI streaming).

Out of Scope

The following features are for extended work:

• MD RAID Topology Mapping: Correlating physical block layer delays to Linux MD software RAID arrays.
• TUI/Dashboard Interface: Custom ncurses-based terminal UI for live drive health monitoring.
• Overhead Benchmarking: Micro-benchmarking eBPF ring buffer strain under extreme I/O workloads.

Installation & Dependencies

Requires clang, llvm, libelf-dev, and bpftool.

To compile the eBPF bytecode and userspace app use make

Usage & Simulation

Run the userspace loader:

sudo ./efhs-app

To see raw debug logs out of the kernel sensor during development:

sudo cat /sys/kernel/debug/tracing/trace_pipe

Development Log & Findings

• June 2026: Got the build system working. Verified that the block_rq_issue hook is successfully catching background disk I/O from system daemons like kworker and jbd2.
• July 2026: Streamlined the build system to link against global system dependencies (-lbpf and system bpftool) rather than compiling them locally. Kernel code made to push live structures into a BPF Ring Buffer, eliminating the need to read trace_pipe and allowing the userspace C app to process and print structured I/O events in actively.

eBPF Reference List

• ebpf.io (General architecture)
• Kernel.org BPF Maps (Hash map details)
• Man7 bpf-helpers (Helper function signatures)
• eBPF Docs Reference (Interactive helper guide)