# namhyung/uftrace architecture

> Architecture diagram of the GitHub repository namhyung/uftrace, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-03-17). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/namhyung/uftrace
- Repository: https://github.com/namhyung/uftrace

## Overview

##### 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.

## Diagram (Mermaid)

```mermaid
graph TD
    subgraph "User Interaction Layer"
        UI["uftrace CLI (uftrace.c/h)"]:::ui
        RC["Record Command"]:::ui
        RP["Replay Command"]:::ui
        GC["Graph Command"]:::ui
        RPT["Report Command"]:::ui
        SC["Script Command"]:::ui
        TC["TUI Command"]:::ui
        GDB["GDB Integration"]:::integration
        PY["Python Integration"]:::scripting
        LP["Lua/Python Scripts"]:::scripting
    end

    subgraph "Core Engine Layer"
        CORE["Core Tracing Engine (uftrace core)"]:::core
        DI["Dynamic Instrumentation (libmcount & arch)"]:::dyn
    end

    subgraph "Data Processing & Analysis Layer"
        DCF["Data Collection & Filtering (utils)"]:::analysis
        AR["Analysis & Reporting"]:::analysis
    end

    UI -->|"commands"| CORE
    CORE -->|"initializes"| DI
    CORE -->|"sends_trace_data"| DCF
    DCF -->|"processed_data"| AR
    RC -->|"triggers"| AR
    RP -->|"triggers"| AR
    GC -->|"triggers"| AR
    RPT -->|"triggers"| AR
    SC -->|"triggers"| AR
    TC -->|"triggers"| AR
    PY -->|"custom_hooks"| CORE
    LP -->|"script_analysis"| AR
    GDB -->|"integrates_with"| PY

    click UI "https://github.com/namhyung/uftrace/blob/master/uftrace.c"
    click RC "https://github.com/namhyung/uftrace/blob/master/cmds/record.c"
    click RP "https://github.com/namhyung/uftrace/blob/master/cmds/replay.c"
    click GC "https://github.com/namhyung/uftrace/blob/master/cmds/graph.c"
    click RPT "https://github.com/namhyung/uftrace/blob/master/cmds/report.c"
    click SC "https://github.com/namhyung/uftrace/blob/master/cmds/script.c"
    click TC "https://github.com/namhyung/uftrace/blob/master/cmds/tui.c"
    click CORE "https://github.com/namhyung/uftrace/blob/master/uftrace.c"
    click DI "https://github.com/namhyung/uftrace/blob/master/libmcount/mcount.c"
    click DCF "https://github.com/namhyung/uftrace/blob/master/utils/auto-args.c"
    click AR "https://github.com/namhyung/uftrace/blob/master/utils/graph.c"
    click PY "https://github.com/namhyung/uftrace/blob/master/python/uftrace.py"
    click LP "https://github.com/namhyung/uftrace/blob/master/scripts/dump.lua"
    click GDB "https://github.com/namhyung/uftrace/tree/master/gdb/uftrace"

    classDef ui fill:#ffcc00,stroke:#000,stroke-width:2px;
    classDef core fill:#ccffcc,stroke:#000,stroke-width:2px;
    classDef dyn fill:#cce5ff,stroke:#000,stroke-width:2px;
    classDef analysis fill:#ffcccc,stroke:#000,stroke-width:2px;
    classDef scripting fill:#d9d2e9,stroke:#000,stroke-width:2px;
    classDef integration fill:#e6e6e6,stroke:#000,stroke-width:2px;
```
