> ## Documentation Index
> Fetch the complete documentation index at: https://mintlify.com/a16z/jolt/llms.txt
> Use this file to discover all available pages before exploring further.

# Profiling

> Performance profiling tools for Jolt zkVM

Jolt provides comprehensive profiling capabilities to help you analyze and optimize the performance of your zkVM programs.

## Execution Profiling

Jolt uses [tokio-rs/tracing](https://github.com/tokio-rs/tracing) for execution profiling, allowing you to generate detailed traces of your program's execution.

### Basic Trace Generation

To generate an execution trace, run:

```bash theme={null}
cargo run --release -p jolt-core profile --name sha3 --format chrome
```

The `--name` parameter accepts the following benchmark programs:

* `sha2`
* `sha3`
* `sha2-chain`
* `fibonacci`
* `btreemap`

The corresponding guest programs can be found in the [`examples`](https://github.com/a16z/jolt/tree/main/examples) directory. Benchmark inputs are provided in [`bench.rs`](https://github.com/a16z/jolt/blob/main/jolt-core/src/benches/bench.rs).

This command outputs a JSON file in the workspace root with the name `trace-<timestamp>.json`, which can be viewed in [Perfetto](https://ui.perfetto.dev/).

### CPU and Memory Monitoring

To track CPU and memory usage alongside your execution trace, use the `monitor` feature:

```bash theme={null}
cargo run --release --features monitor -p jolt-core profile --name sha3 --format chrome
```

This logs CPU and memory metrics as tracing events. To convert these counter events into Perfetto counter tracks for easier visualization:

```bash theme={null}
# Run profiling with monitor feature
cargo run --release --features monitor -p jolt-core profile --name sha3 --format chrome

# Post-process the trace for better visualization
python3 scripts/postprocess_trace.py benchmark-runs/perfetto_traces/*.json
```

<Note>
  The monitor feature provides real-time insights into resource consumption during proving, which is especially useful for identifying bottlenecks.
</Note>

### CPU Profiling with pprof

For detailed CPU profiling, enable the `pprof` feature:

```bash theme={null}
cargo run --release --features pprof -p jolt-core profile --name sha3 --format chrome
```

This produces a `.pb` profile file that can be viewed using [pprof](https://github.com/google/pprof):

```bash theme={null}
go tool pprof -http=:8080 target/release/jolt-core benchmark-runs/pprof/sha3_prove.pb
```

<Tip>
  The pprof visualization helps identify hot paths in your code, making it easier to optimize performance-critical sections.
</Tip>

## Memory Profiling

Jolt uses [allocative](https://github.com/facebookexperimental/allocative) for memory profiling, allowing you to measure the total heap space occupied by data structures and generate flamegraphs.

### Generating Memory Profiles

Most sumcheck data structures in Jolt implement the `Allocative` trait. Flamegraphs are generated at the start and end of stages 2-5 (see [`jolt_dag.rs`](https://github.com/a16z/jolt/blob/main/jolt-core/src/zkvm/dag/jolt_dag.rs)).

To generate allocative output:

```bash theme={null}
RUST_LOG=debug cargo run --release --features allocative -p jolt-core profile --name sha3 --format chrome
```

The `--name` parameter accepts the same benchmark programs as execution profiling:

* `sha2`
* `sha3`
* `sha2-chain`
* `fibonacci`
* `btreemap`

### Understanding the Output

The command will:

1. Log memory usage information to the command line
2. Output multiple SVG files (e.g., `stage3_start_flamechart.svg`)
3. Generate flamegraphs that can be viewed in any web browser

<Note>
  Memory flamegraphs provide a visual representation of heap allocations, making it easy to identify memory-intensive data structures.
</Note>

## Best Practices

<Tip>
  When profiling:

  * Always use `--release` builds for accurate performance measurements
  * Start with execution profiling to identify slow stages
  * Use memory profiling to optimize heap usage in critical stages
  * Combine multiple profiling techniques for comprehensive analysis
</Tip>

<Warning>
  Debug builds can be orders of magnitude slower than release builds. Always profile with `--release` to get realistic performance data.
</Warning>