# Performance Analysis Scripts
This directory contains scripts for analyzing and comparing flamegraph performance data.
## Scripts
### `analyze_flamegraph.sh`
Analyzes a single flamegraph SVG file and identifies performance bottlenecks.
**Usage:**
```bash
./scripts/analyze_flamegraph.sh <flamegraph.svg>
```
**Example:**
```bash
cargo flamegraph --example counter
./scripts/analyze_flamegraph.sh flamegraph.svg
```
**Output:**
- Total sample count
- Top hotspots (functions with highest sample counts)
- Category breakdown:
- Terminal/Crossterm operations
- Ratatui rendering
- Tokio runtime
- Tears framework
- System calls
- Identified bottlenecks with specific recommendations
- Color-coded output for easy identification:
- 🔴 Red: Critical bottlenecks (≥10%)
- 🟡 Yellow: Moderate issues (≥5%)
- 🟢 Green: Minor or expected overhead (≥1%)
### `compare_flamegraphs.sh`
Compares two flamegraph files to measure the impact of optimizations.
**Usage:**
```bash
./scripts/compare_flamegraphs.sh <before.svg> <after.svg>
```
**Example:**
```bash
# Generate baseline
cargo flamegraph --example counter -o flamegraph_before.svg
# Make your optimizations...
# Generate new flamegraph
cargo flamegraph --example counter -o flamegraph_after.svg
# Compare
./scripts/compare_flamegraphs.sh flamegraph_before.svg flamegraph_after.svg
```
**Output:**
- Total sample comparison
- Key metrics comparison:
- Terminal size queries
- Buffer diffing
- Rendering total
- Idle/parking time
- Tears framework overhead
- Per-metric improvement/regression percentages
- Overall performance summary
## Workflow
### 1. Establish Baseline
```bash
# Run flamegraph on your example or application
cargo flamegraph --example counter -o baseline.svg
# Analyze to identify bottlenecks
./scripts/analyze_flamegraph.sh baseline.svg
```
### 2. Make Optimizations
Based on the analysis, implement optimizations in your code.
### 3. Measure Impact
```bash
# Generate new flamegraph
cargo flamegraph --example counter -o optimized.svg
# Compare with baseline
./scripts/compare_flamegraphs.sh baseline.svg optimized.svg
```
### 4. Iterate
Repeat the process until performance meets your requirements.
## Tips
### Generating Flamegraphs
- **Run for sufficient time**: Let the example run for at least 10-20 seconds to collect enough samples
- **Focus on specific scenarios**: Profile the specific use case you want to optimize
- **Use release builds**: Add `--release` for production-like performance (but debug builds show more detail)
```bash
# Debug build (more detailed symbols)
cargo flamegraph --example counter
# Release build (production performance)
cargo flamegraph --release --example counter
```
### Interpreting Results
- **Sample counts are relative**: Higher samples = more time spent
- **Flamegraph width**: Wider bars = more samples = more time
- **Stack depth**: Shows call hierarchy
- **System time**: Includes OS calls and waiting
- **Idle time**: `park` and `wait` functions are expected in async runtimes
### Common Bottlenecks in TUI Applications
1. **Terminal I/O**: Opening `/dev/tty` repeatedly, excessive ioctl calls
2. **Buffer operations**: Full screen diffs every frame
3. **Rendering frequency**: Drawing when nothing changed
4. **Event polling**: Inefficient event loop design
5. **Allocation**: Excessive memory allocation in hot paths
## Requirements
- Bash (macOS/Linux)
- `grep`, `sed`, `awk` (standard Unix tools)
- `bc` (for floating-point arithmetic in comparisons)
## Notes
- These scripts are designed for flamegraphs generated by `cargo-flamegraph` or compatible tools
- HTML entities in function names are automatically decoded
- Color output requires ANSI terminal support