termpprof

A self-contained, terminal-only CPU profiler for Linux. termpprof is intended to attach to (or spawn) a process, sample its call stacks at approximately 99 Hz, unwind and symbolize those stacks, and render a live, interactive ASCII/block-character flame graph — all without depending on any other installed program.

The project is currently under active development.

Current status: Phase 1 — project foundation

Phase 1 is complete. It establishes the project layout, build system, CLI, configuration model, logging, and the interfaces future phases will implement — but no profiling functionality exists yet. Running termpprof validates its arguments and reports what it would do; it does not attach to processes, spawn them, sample stacks, unwind, symbolize, or render anything.

$ termpprof --pid 1234
termpprof
CPU profiler for Linux

PID mode:
  target PID: 1234
  sampling frequency: 99 Hz
  backend: ptrace

Profiler backend is not implemented yet.

Planned architecture

Sampler
   ↓
Raw Samples
   ↓
Unwinder
   ↓
Symbolizer
   ↓
Aggregator
   ↓
Renderer  (and Exporter, off the same aggregated data)

See docs/architecture.md for the full design, including why the renderer is meant to consume immutable snapshots rather than a tree being concurrently mutated by the sampler.

Planned sampling backends

• ptrace
• perf_event_open

Planned symbolization

• ELF symbol tables
• DWARF line number information

Build

Requires a C++20 compiler, CMake 3.20+, and Linux.

cmake -S . -B build
cmake --build build
./build/termpprof --help

Or with presets:

cmake --preset debug
cmake --build --preset debug
./build/debug/termpprof --help

Running tests

cmake -S . -B build -DTERMPPROF_BUILD_TESTS=ON
cmake --build build
ctest --test-dir build

CLI

termpprof [OPTIONS]
termpprof [OPTIONS] --pid <PID>
termpprof [OPTIONS] -- <command> [args...]

  --pid <PID>       Attach to an existing process by PID
  --hz <N>          Sampling frequency in Hz (default: 99)
  --mode <MODE>     Profiler backend: ptrace (default) or perf
  --help, -h        Show help text and exit
  --version         Show version information and exit

--pid and a trailing command are mutually exclusive: termpprof targets exactly one of an existing process or a command to spawn.

Dependencies

None beyond the C++ standard library, POSIX/Linux headers, and CMake. This is deliberate: termpprof aims to ship as a self-contained, ideally statically linked binary with no runtime dependency on other installed programs. A TUI dependency (FTXUI) will be introduced later, scoped to the rendering phase only.

Roadmap

Phase 1  Project foundation                    [done]
Phase 2  ptrace process control
Phase 3  frame-pointer unwinding
Phase 4  ELF symbolization
Phase 5  sampling + aggregation
Phase 6  ASCII flame graph
Phase 7  interactive TUI
Phase 8  DWARF unwinding
Phase 9  perf_event_open backend
Phase 10 static builds + release hardening

License

MIT