Intra-thread task finder (itt-finder)

itt-finder analyzes folded stack traces and extracts intra-thread task candidates from them. It includes a helper script, trace.sh, to capture stacks from a live Linux process with perf.

Repository Layout

• src/: main Rust application
• third-party/FlameGraph/: Brendan Gregg's FlameGraph tools, used by trace.sh
• trace.sh: helper script for tracing a running process and invoking itt-finder

Prerequisites

Build prerequisites

• Rust toolchain with cargo

Tracing prerequisites

• Linux with perf installed
• sudo access for perf record
• third-party/FlameGraph present in this repository

If you cloned the repository without submodules, initialize them first:

git submodule update --init --recursive

Build

Build a release binary with:

cargo build --release

The binary will be available at:

./target/release/itt-finder

itt-finder CLI

The main CLI accepts a folded stack file as input:

./target/release/itt-finder <FILE_PATH> [OPTIONS]

Key options:

• -b, --binary <BINARY>: binary used for symbol resolution
• -o, --out <OUT>: write JSON output to a file instead of stdout
• -s, --size <SIZE>: limit the number of reported tasks
• --tui: launch the interactive task-selection TUI
• --no-stdlib-exclusion: disable stdlib symbol exclusion

Example:

./target/release/itt-finder results/my-app.folded \
  --binary /path/to/my-app \
  --out results/my-app.json

trace.sh

trace.sh automates a common workflow for a running Linux process:

1. Record samples with perf
2. Collapse stacks into folded format
3. Generate a flame graph SVG
4. Run itt-finder on the folded stacks

Basic usage:

bash trace.sh <PID> [OPTIONS]

Examples:

bash trace.sh 1234
bash trace.sh 1234 --duration 60
bash trace.sh 1234 --tid 1240
bash trace.sh 1234 --list-threads
bash trace.sh 1234 -x "--size 50"
bash trace.sh 1234 --no-analysis

trace.sh options

• --tid TID: trace a specific thread instead of the main thread
• --duration SECONDS: trace duration, default 30
• -x, --parser-args ARG: extra arguments forwarded to itt-finder
• --list-threads: list threads for the target PID and exit
• --no-analysis: stop after perf capture and flame graph generation

What trace.sh produces

Outputs are written under ./results/ using the process name and PID:

• <name>-<pid>.data: raw perf record output
• <name>-<pid>.folded: folded stack trace
• <name>-<pid>.svg: flame graph
• <name>-<pid>.json: itt-finder JSON output, unless --no-analysis is used

The JSON output identifies candidate intra-thread tasks. Use it to guide how LiME's lime-it branch should approach intra-thread task modeling.

Notes

• trace.sh detects the traced binary from /proc/<pid>/exe and passes it to itt-finder for symbol resolution.
• If the script is run in an interactive terminal, it tries to launch itt-finder --tui.
• If TUI startup fails, it falls back to non-interactive mode automatically.
• The script traces a single thread with perf record -t.

Typical Workflow

Build once:

cargo build --release

Inspect a process and list threads:

bash trace.sh 1234 --list-threads

Trace one thread and produce parser output:

bash trace.sh 1234 --tid 1240

Troubleshooting

• If trace.sh says perf is missing, install your distribution's perf package.
• If trace.sh says third-party/FlameGraph is missing, initialize submodules.
• If the folded file is empty, the target may not have been CPU-active during the recording window.
• If the discovered intra-thread tasks are inaccurate, make sure the traced binary is available and includes usable debug symbol information.

Related Paper

This tool is part of the project described in B. Ye, F. Marković, and B. Brandenburg, "Framework-Agnostic Model Inference for Intra-Thread Real-Time Tasks," Proceedings of the 32nd IEEE Real-Time and Embedded Technology and Applications Symposium (RTAS 2026), to appear, May 2026.