hipfile/util: USDT (user statically-defined tracing) powered ais-stats.py

[kurtmcmillan]

Motivation

Clients will want some visibility into the behavior of hipfile. This PR adds USDT probes to hipfile and provides an example script to attach to these probes and output statistics after the client program exits. Since this is an experiment there is lots of room for improvement and additional funcitonality.

Technical Details

USDT probes are added to hipfile's IO path. The ais-stats.py script spawns the client process and enables the USDT probes before the client program begins execution. Once the client program terminates, ais-stats.py outputs the collected statistics.

[kurtmcmillan]

Example using ais-stats.py:

aiscp rand.dat rand.dat.cp

... no output ...

sudo ais-stat.py aiscp rand.dat rand.dat.cp

AIS read: 1048576 bytes
AIS write: 1048576 bytes
POSIX read: 0 bytes
POSIX write: 0 bytes

sudo HIPFILE_FORCE_COMPAT_MODE=true ais-stat.py aiscp rand.dat rand.dat.cp

AIS read: 0 bytes
AIS write: 0 bytes
POSIX read: 1048576 bytes
POSIX write: 1048576 bytes

[Copilot]

Pull request overview

This PR adds User Statically-Defined Tracing (USDT) support to hipfile, enabling runtime observability of IO operations. The implementation includes USDT probe definitions in the IO path and provides a Python script to collect and display statistics when attached to a client process.

Changes:

• Added USDT library header for defining and triggering tracepoints with zero overhead
• Integrated USDT probes into both AIS and POSIX IO paths to track read/write operations
• Created a Python script that uses BPF to attach to USDT probes and collect IO statistics

Reviewed changes

Copilot reviewed 6 out of 6 changed files in this pull request and generated 2 comments.

Show a summary per file

File	Description
util/ais-stat.py	Python script using BCC/BPF to spawn client processes and collect USDT-based IO statistics
src/amd_detail/usdt.h	Single-header USDT library providing macros for defining tracepoints
src/amd_detail/trace.h	Wrapper header defining hipfile-specific USDT macros
src/amd_detail/backend/fastpath.cpp	Added USDT probe for AIS IO operations
src/amd_detail/backend/fallback.cpp	Added USDT probe for POSIX IO operations
.clang-format-ignore	Excluded usdt.h from clang-format to preserve upstream formatting

Comments suppressed due to low confidence (1)

util/ais-stat.py:1

• The ## token pasting operator and __VA_OPT__ are being used incorrectly together. Line 291 uses ##__VA_ARGS__ but should use __VA_OPT__(,) __VA_ARGS__ to match the pattern in line 294, which is inside the #else block. The positions of these two lines appear to be swapped.

#! /usr/bin/env python3

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[Copilot]

The function name is incorrect: printf should be print. This will cause a NameError at runtime.

Suggested change

	printf("ais-stat must be run as root", file=sys.stderr)
	print("ais-stat must be run as root", file=sys.stderr)

[Copilot]

Changed 'hipfile statistics' to 'HIPfile statistics' for consistency with project naming conventions.

Suggested change

	description="hipfile statistics"
	description="HIPfile statistics"

[kurtmcmillan]

Closing. Instead of using USDT which requires sudo hipfile will used shared memory to share statistics.