# perf report

**`perf report` analyzes recorded samples** from `perf.data` and shows which functions consumed the most CPU time. It opens an interactive text UI where you can explore call graphs and filter results.

```bash
perf record -g ./program    # record with call graphs
perf report                 # open interactive browser
```

The interactive view shows a table of functions sorted by percentage of total samples. Each line shows the function name, percentage of time, and number of samples. Press Enter on a function to expand its call graph and see which callers invoked it and which functions it called.

```bash
perf report --stdio        # non-interactive text output (useful for scripts)
perf report -i mydata.data # analyze a specific perf.data file
```

`--stdio` prints the entire report to stdout instead of opening an interactive UI. This is useful for scripts or when running over SSH without X11 forwarding. `-i` specifies a data file other than `perf.data`.

**Filtering and sorting:**

```bash
perf report --sort comm,pid,dso       # sort by command, process ID, library
perf report --dsos libmpi.so          # show only samples from libmpi.so
perf report --symbols my_function     # filter to specific function
```

By default, perf sorts by percentage of samples. `--sort` changes the sort order. `--dsos` filters to a specific library or binary. `--symbols` shows only specific functions.

**Interpretation:** The percentage next to each function is the fraction of samples (CPU time) spent in that function and everything it calls. A function at 30% means the CPU was executing that code path 30% of the time.

When you expand a function with Enter, you see its **children** (functions it calls) and **parents** (functions that call it). The "Children" and "Self" columns distinguish between time spent in the function itself versus time in its callees. A function with high "Children" but low "Self" means it's a wrapper; the actual work is in its children.

**Example workflow:** Start by looking at the top 10 functions in `perf report`. If a high-percentage function is a library call (like `MPI_Send`), expand it to see the call chain above it—which application function is calling the library. This tells you where the bottleneck is in your code, not just in the libraries.

**Comparing profiles:**

```bash
perf report --baseline perf-before.data --compare perf-after.data
```

This compares two profiles and highlights which functions changed the most. Useful for validating that an optimization actually helped (or didn't).