# piano

Automated instrumentation-based profiling for Rust. Point it at your project, get back timing, percentiles, and allocation counts per frame.

```
$ piano profile
found 5 function(s) across 3 file(s)
built: target/piano/debug/my-project
... normal program output ...

Function                                    Calls       Self        p50        p99   Allocs      Bytes
----------------------------------------------------------------------------------------------------
parse                                          12   341.21ms    28.11ms    32.44ms      840     62.5KB
resolve                                        47   141.13ms     2.98ms     3.22ms      329     24.1KB
parse_item                                    108    94.58ms     0.87ms     1.14ms     1620    126.3KB

3000 frames
```

Or step by step:

```
$ piano build
found 5 function(s) across 3 file(s)
built: target/piano/debug/my-project

$ piano run
... normal program output ...

$ piano report
```

Piano rewrites your source at the AST level to inject RAII timing guards and an allocation-tracking allocator, builds the instrumented binary, and flushes per-frame results to `target/piano/runs/` on process exit. Your original source is never modified.

## Install

```
cargo install piano
```

Requires Rust 1.88+.

## Usage

### Instrument and build

By default, `piano build` instruments all functions in your project:

```
$ piano build
found 5 function(s) across 3 file(s)
built: target/piano/debug/my-project
```

Narrow scope by name, file, or module:

```
$ piano build --fn parse                    # functions containing "parse"
$ piano build --fn "Parser::parse"          # specific impl method
$ piano build --file src/lexer.rs           # all functions in a file
$ piano build --mod resolver                # all functions in a module
$ piano build --fn parse --fn resolve       # multiple patterns
```

The instrumented binary is written to `target/piano/debug/<name>`.

### Execute the instrumented binary

`piano run` finds and executes the most recently built instrumented binary:

```
$ piano run
$ piano run -- --input data.csv --verbose    # pass arguments after --
```

It looks in `target/piano/debug/` and picks the most recent executable. Piano exits with the binary's exit code.

### One-step profiling

`piano profile` combines build, execute, and report into one command:

```
$ piano profile --fn parse -- --input data.csv
```

### Per-frame profiling

Each instrumented run records per-frame timing and allocation data. The default `piano report` shows aggregate percentiles (above). Use `--frames` for a per-frame breakdown with spike detection:

```
$ piano report --frames
 Frame      Total        parse      resolve   parse_item   Allocs      Bytes
-----------------------------------------------------------------------
     1    48.12ms      28.11ms       2.98ms       0.87ms       93     21.3KB
     2    49.01ms      28.50ms       3.01ms       0.91ms       95     21.8KB
     3    47.88ms      27.94ms       2.95ms       0.85ms       91     20.9KB
     4   102.33ms      71.22ms       3.10ms       1.05ms      210     48.7KB <<
     5    48.55ms      28.30ms       3.00ms       0.89ms       94     21.5KB

5 frames | 1 spikes (>2x median)
```

Frames exceeding 2x the median total time are marked with `<<`.

### Tag and compare runs

```
$ piano tag baseline
tagged 'baseline' -> 98321_1740000000000

# ... make changes, rebuild, re-run ...

$ piano tag current
tagged 'current' -> 98321_1740000060000

$ piano diff baseline current
Function                                     Before      After      Delta     Allocs    A.Delta
----------------------------------------------------------------------------------------------
parse                                       341.21ms    198.44ms   -142.77ms        640       -200
resolve                                     141.13ms    141.09ms     -0.04ms        329         +0
parse_item                                   94.58ms     88.12ms     -6.46ms       1240       -380
```

`piano report` and `piano diff` accept file paths or tag names.

### CPU time

Add `--cpu-time` to measure per-thread CPU time alongside wall-clock time (Linux + macOS, 64-bit only):

```
$ piano build --cpu-time
```

The report adds CPU columns so you can distinguish computation from I/O or sleeping.

### Multi-threaded programs

Programs using rayon or `std::thread::spawn` work out of the box. Each thread writes its own timing data with a shared `run_id`. `piano report` consolidates all files from the same run automatically.

## How it works

1. `piano build` copies your project to a staging directory
2. Adds `piano-runtime` as a dependency in the staged `Cargo.toml`
3. Parses Rust source with `syn`, finds functions matching your patterns, and injects `let _guard = piano_runtime::enter("name")` at the top of each
4. Sets `PianoAllocator` as the global allocator to track per-frame heap activity
5. Builds with `cargo build`

Each guard records wall-clock time on construction and drop. Self-time is computed by subtracting children's time from total time. The allocator attributes heap operations to the currently executing instrumented function, and frame summaries are computed when top-level guards complete.

Two crates: `piano` (CLI, AST rewriting, build orchestration) and `piano-runtime` (zero-dependency timing and allocation runtime injected into user projects). The runtime has zero external dependencies to avoid version conflicts.

## Limitations

- Wall-clock timing by default. Use `--cpu-time` to add per-thread CPU time (Linux + macOS only).
- Functions shorter than the guard overhead (~12ns on x86-64, sub-nanosecond on Apple Silicon) will have noisy measurements.
- Async functions record wall time only when futures migrate across threads (self-time may overcount).
- Allocation tracking counts heap operations only (`alloc`/`dealloc`). Stack allocations and memory-mapped regions are not tracked.

## License

MIT
