stax

# record a program (or attach to a running one with --pid)
stax record -- ./target/release/mybench

# from another shell — or to an AI agent — query the live run
stax wait --for-samples 10000     # block until data lands
stax top -n 10 --sort self        # hottest leaf functions
stax flame -d 6                   # on-CPU flamegraph, as a tree
stax annotate 'mycrate::hot_fn'   # per-instruction sample counts

stax is a live version of Instruments.app: on-CPU and off-CPU stacks as flamegraphs, top-N functions, per-thread breakdowns, and annotated disassembly — all queryable while the recording is still running, from a terminal, a browser, or an AI agent.

It started as a fork of not-perf with macOS bits borrowed from samply, and is now very much its own codebase. On macOS it uses the private kperf/kdebug frameworks, so it sees things samply can't — at the cost of a privileged helper daemon.

Choose your path

Guide

Learn stax step by step

Install the daemons, record your first run, read flamegraphs, profile JIT'd code, and troubleshoot when something goes wrong.

Concepts

Understand how it works

The three-process architecture, what each platform can capture, how stacks get unwound, and what sampling actually measures.

Reference

Look it up fast

Every subcommand and flag, the RPC services for programmatic clients, environment variables, and exit codes.

Why stax

• Live, not post-mortem. There is no record-then-open step. The aggregator updates continuously; stax top, stax flame, and the web UI all read the current state of a run that is still going.
• Built for agents as much as humans. Every query is a subcommand with plain-text output and meaningful exit codes. stax wait --for-samples N lets a script block until there's enough data to look at.
• On-CPU and off-CPU. On macOS, stax correlates kdebug scheduler events, so it knows not just where the CPU time goes but why a thread was blocked — lock, sleep, I/O, IPC.
• Down to the instruction. stax annotate disassembles a hot function and attributes samples to individual instructions, interleaved with source.
• JIT-aware. A JIT that emits a perf jitdump file gets its compiled functions symbolicated and disassembled like any other code.

Quick links

• Getting Started — install the daemons and verify
• Recording a Run — launch a target or attach to a PID
• Architecture — stax, stax-server, staxd
• Stack Unwinding — why your build needs frame pointers
• CLI Reference — every subcommand and flag
• GitHub — source and issues