# Viewing Benchmark Visualizations

Quick guide to viewing the interactive benchmark reports generated by Criterion.

## Prerequisites

For the best visualizations, install Gnuplot:

```bash
# macOS
brew install gnuplot

# Ubuntu/Debian
sudo apt-get install gnuplot

# Windows
# Download from http://www.gnuplot.info/
```

**Note**: Benchmarks work without Gnuplot, but you'll get better visualizations with it installed.

## Running Benchmarks

```bash
cargo bench
```

This will:
1. Run all benchmarks
2. Generate statistics
3. Create HTML reports with interactive charts
4. Save results in `target/criterion/`

## Viewing Reports

### Main Report (Start Here)

```bash
# macOS
open target/criterion/report/index.html

# Linux
xdg-open target/criterion/report/index.html

# Windows
start target/criterion/report/index.html

# Or manually navigate to:
# file:///path/to/your/project/target/criterion/report/index.html
```

### Individual Benchmark Reports

Each benchmark has its own detailed report:

```bash
# Simple citations
open target/criterion/simple_citations/inline_numeric/report/index.html

# Complex document
open target/criterion/complex_document/full_document/report/index.html

# Real-world ChatGPT
open target/criterion/real_world/chatgpt_format/report/index.html

# Real-world Perplexity
open target/criterion/real_world/perplexity_format/report/index.html

# Batch processing
open target/criterion/batch_processing/5_documents/report/index.html

# Edge cases
open target/criterion/edge_cases/no_citations/report/index.html
open target/criterion/edge_cases/only_citations/report/index.html
```

## Report Structure

```
target/criterion/
├── report/
│   └── index.html                    # 📊 Main report (start here)
│
├── simple_citations/
│   └── inline_numeric/
│       ├── report/
│       │   └── index.html            # Individual benchmark report
│       ├── base/                     # Baseline data (if saved)
│       └── new/                      # Latest run data
│
├── complex_document/
│   └── full_document/
│       └── report/
│           └── index.html
│
├── real_world/
│   ├── chatgpt_format/
│   │   └── report/
│   │       └── index.html
│   └── perplexity_format/
│       └── report/
│           └── index.html
│
├── batch_processing/
│   └── 5_documents/
│       └── report/
│           └── index.html
│
└── edge_cases/
    ├── no_citations/
    │   └── report/
    │       └── index.html
    └── only_citations/
        └── report/
            └── index.html
```

## What You'll See

### Main Report Page

- **Summary table** - All benchmarks with their performance metrics
- **Links to individual reports** - Click any benchmark for details
- **Comparison data** - If you've saved baselines

### Individual Benchmark Reports

Each benchmark report includes:

1. **Line Chart** - Performance over time
   - Shows how performance changes across runs
   - Useful for detecting regressions

2. **Violin Plot** - Distribution of measurements
   - Shows the spread of timing measurements
   - Helps identify outliers

3. **PDF Plot** - Probability density function
   - Statistical distribution of measurements
   - Shows where most measurements fall

4. **Statistics Table**
   - Mean, median, standard deviation
   - Confidence intervals
   - Outlier information

5. **Comparison Charts** (if using baselines)
   - Before/after comparison
   - Percentage change
   - Statistical significance

## Using Baselines for Comparison

### Save a Baseline

Before making changes:

```bash
cargo bench -- --save-baseline before
```

### Make Your Changes

Edit your code...

### Compare Against Baseline

```bash
cargo bench -- --baseline before
```

The reports will now show:
- Performance difference (faster/slower)
- Percentage change
- Statistical significance (p-value)

### View Comparison

```bash
open target/criterion/report/index.html
```

Look for:
- **Green** - Performance improved
- **Red** - Performance regressed
- **Gray** - No significant change

## Tips

### Bookmark the Report

Add this to your browser bookmarks:
```
file:///path/to/your/project/target/criterion/report/index.html
```

Replace `/path/to/your/project/` with your actual project path.

### Auto-Open After Benchmarks

Create a shell alias:

```bash
# Add to ~/.bashrc or ~/.zshrc
alias benchview='cargo bench && open target/criterion/report/index.html'
```

Then just run:
```bash
benchview
```

### Quick Navigation

From the main report:
1. Click any benchmark name to see its detailed report
2. Use browser back button to return to main report
3. Use "Index" link at top of each page to return to main report

## Troubleshooting

### Reports Not Generated

**Problem**: No HTML files in `target/criterion/`

**Solution**:
1. Make sure benchmarks ran successfully: `cargo bench`
2. Check for errors in benchmark output
3. Verify Criterion is in `[dev-dependencies]` in Cargo.toml

### Charts Not Showing

**Problem**: HTML opens but no charts visible

**Solution**:
1. Install Gnuplot: `brew install gnuplot` (macOS)
2. Re-run benchmarks: `cargo bench`
3. Check browser console for JavaScript errors

### Old Data Showing

**Problem**: Reports show old benchmark results

**Solution**:
```bash
# Clean old data
rm -rf target/criterion

# Re-run benchmarks
cargo bench
```

## Further Reading

- [Criterion.rs User Guide](https://bheisler.github.io/criterion.rs/book/)
- [Understanding Benchmark Statistics](https://bheisler.github.io/criterion.rs/book/user_guide/command_line_output.html)
- [Main BENCHMARKING.md Guide](BENCHMARKING.md)

---

**Quick Reference**:
```bash
# Run benchmarks
cargo bench

# View results
open target/criterion/report/index.html
```

