# perf Scripting

**`perf script` exports profiling data** in a human-readable format, enabling custom analysis and integration with other tools. It's the bridge between perf's binary `perf.data` and external scripts.

```bash
perf record ./program
perf script                          # dump all samples as text
perf script -i mydata.data           # analyze specific file
perf script --stdio                  # explicit non-interactive output
```

By default, `perf script` reads `perf.data` in the current directory and prints every sample to stdout. Each line is a sample with timestamp, process ID, CPU, event count, function name, and optionally the call stack.

**Example output:**

```
program  1234 [000] 1234.567890: 10000 cycles:ppp:
      ffffffff810d1234 copy_user_generic_string (/lib/modules/...vmlinuz)
        7f1234abcd56 my_function (program)
        7f1234abcd78 main (program)
```

Each line shows: process name, PID, CPU core, timestamp, event, and stack trace (if recorded with `-g`).

**Filtering output:**

```bash
perf script -p program_name          # only samples from specific process
perf script -s bin/my_tool.py        # run custom Python script on samples
```

The `-p` flag filters to specific processes. The `-s` flag invokes a custom script (Python, Perl) instead of just dumping text. perf can call Python directly: write a script that processes each sample.

**Custom Python scripts:** perf supports Python-based analysis via `-s`:

```python
#!/usr/bin/env python
# analyze_samples.py
def trace_begin():
    print("Profiling started")

def trace_end():
    print("Profiling ended")

def sample(sample_dict):
    # Called for each sample
    print(sample_dict['ev_name'], sample_dict['sym'])
```

Run with: `perf script -s analyze_samples.py`. The script receives sample dictionaries for each event.

**Extracting specific data:**

```bash
perf script > all_samples.txt
grep my_function all_samples.txt | wc -l     # count samples in my_function
grep -o "0x[0-9a-f]*" all_samples.txt | sort | uniq | wc -l  # unique addresses
```

Pipe `perf script` output to grep, awk, or other text tools for custom analysis. This is useful for building statistics or filtering data.

**Integration with FlameGraph:**

```bash
perf script | stackcollapse-perf.pl | flamegraph.pl > flame.svg
```

`perf script` exports data in a format that `stackcollapse-perf.pl` understands. It aggregates individual samples into complete stack traces, which `flamegraph.pl` then visualizes.

**Performance:** `perf script` can be slow on large `perf.data` files (gigabytes of samples). For analysis on HPC systems, consider:
1. Reducing data during collection: lower sampling rate, filter to specific events, or record for shorter duration.
2. Processing on the compute node where the data is, then transferring only aggregated results.
3. Using `perf report --stdio` for simple per-function analysis (faster than `perf script`).

**Data portability:** `perf.data` is portable between machines with the same kernel version and binary symbols. Profiling on the compute system and analyzing locally requires the binary and symbol information on your local machine. For reproducible analysis in HPC, keep binaries and debug symbols alongside profile data.