How namhyung/uftrace works
Project Type and Overall Purpose
• Project Type: A tracing/profiling tool and call graph tracer.
• Purpose: It records function call events at both user and kernel levels, offers dynamic patching (without recompilation), provides filtering options, and outputs several kinds of reports (graph, replay, dump, etc.). It also has integrations for Python/Lua scripting and GDB support.
Key File Structure
• Architecture-specific Code (arch/): Contains distinct directories (aarch64, arm, i386, risc-v, x86_64) each with their own Makefile and assembly/C files. This indicates modular support for different CPU architectures – central to implementing dynamic instrumentation and patching.
• Core Engine and Main Interfaces:
• uftrace.c/uftrace.h: Likely the main entry point.
• cmds/: Contains individual command implementations (record, replay, graph, info, dump, etc.).
• libmcount/: Provides the mcount (profiling) implementation used by the tracer engine including the dynamic and PLT hooking mechanisms.
• utils/: Hosts a variety of helper modules such as for symbol resolution, argument filtering, event processing, reporting, graph generation, and even supporting output for tools like Chrome trace or flame graphs.
• Scripting and Extensions:
• python/ and scripts/: Contain integrations with Python and Lua, providing APIs and scripts that enable custom analyses.
• Testing and Documentation:
• tests/: A comprehensive suite of test cases demonstrating broad coverage on multiple architectures and various tracing scenarios.
• doc/: Documentation, tutorials, and examples to explain usage and integration in real-world scenarios.
• Integration/DevOps:
• .github/workflows/, Makefile(s), and misc/: These support continuous integration, dependency checking, debugging utilities, and environment setups (including Docker configurations).
Main Components
a. User Interface and Command Layer:
• Command-line interface (CLI) which accepts commands like record, replay, report, info, graph, dump, script, and tui.
• GDB integration (gdb/ directory) as an external debugging helper.
b. Core Tracing Engine:
• The central module (uftrace core/uftrace.c and associated modules) that coordinates tracing:
• It initializes based on command-line options and selects the appropriate mode (recording trace or replaying data).
• Interfaces with libraries and OS-level features (perf events, ftrace, etc).
c. Dynamic Instrumentation and Hooking Subsystem:
• libmcount module: Handles hooking techniques such as dynamic patching, PLT hooking of library functions, and inserting mcount calls.
• Architecture-specific modules in arch/ (e.g., x86_64, aarch64, etc.) which tailor the instrumentation for each CPU’s calling conventions and assembly patterns.
d. Data Collection and Storage:
• Components that record timestamps, function arguments, return values, and system events, storing data in trace files (uftrace.data).
• Filtering and auto-argument resolution modules included in utils/ (e.g., auto-args.c/h, filter.c/h, and demangle.c/h).
e. Data Analysis and Reporting Components:
• Replay, report, and graph command modules (located under cmds/) that process collected trace data.
f. Scripting and Extensibility Interfaces:
• Python and Lua modules (in python/ and scripts/) that allow users to write custom scripts to analyze or modify trace data.
• Integration points where those scripts interact with the main engine.
Relationships and Interactions
• The CLI accepts user commands and forwards them to the appropriate handler (record vs. replay vs. report, etc.).
• The record command triggers the initialization of the tracing engine which selects the proper dynamic instrumentation method based on CPU architecture (via arch/ modules) and linking libraries (libmcount).
• Collected data is funneled through filtering and symbol resolution modules (utils/) that enrich the trace data before it’s stored.
• The replay/report/graph commands then read the stored trace data, process it with filtering (also supported by utils) and sequence reconstruction, and output visualization-ready data.
• Scripting engines hook into this processing chain to allow for further custom analyses.
• GDB integration provides an alternate debugging/inspection view by leveraging additional Python scripts in the gdb/ folder.