zprofile - Bundle Performance Profiler¶

zprofile            # Run profiling (build bundle if needed)
zprofile --rebuild  # Force rebuild of profile bundle
zprofile --report   # Show last profiling report (no shell restart)
zprofile --help     # Show help
```bash

## Features

- **Automatic Bundle Building**: Creates instrumented bundle on first run
- **Cache Invalidation**: Detects when source files change and rebuilds
- **Detailed Timing**: Tracks time for each file and directory
- **P10k Theme Timing**: Special instrumentation for Powerlevel10k theme engine
- **Visual Report**: Bar charts and percentages for easy analysis
- **Recommendations**: Automated performance suggestions

## Output Files

| File                                 | Description                |
| ------------------------------------ | -------------------------- |
| `~/.cache/zshand/zshand-profile.zsh` | Instrumented source bundle |
| `~/.cache/zshand/zshand-profile.zwc` | Compiled bytecode          |
| `~/.cache/zshand/profile-timing.log` | Raw timing data            |

## Report Sections

### Directory Timing

Shows time spent in each major directory category:

- `shared_functions` - Common utility functions
- `startup` - Early initialization scripts
- `core` - Framework core configuration
- `functions` - User functions
- `widgets` - ZLE widgets
- `hooks` - Tool integrations
- `plugins` - User plugins
- `init.d` / `post.d` - User early/late scripts

### Special Timing

Tracks components that load outside the bundle:

- `p10k-engine` - Powerlevel10k theme engine initialization

### Slowest Files

Lists the top 10 slowest individual files with timing.

### Recommendations

Automated suggestions based on timing data:

- Files exceeding percentage thresholds
- Lazy loading opportunities
- Optimization suggestions

## Example Output

```bash
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
  ZSHAND PROFILE BUNDLE REPORT
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

📊 Directory Timing:
  core:                      4.1ms  ████████████░░░░░░░░  22%
  plugins:                   3.2ms  ██████████░░░░░░░░░░  17%
  shared_functions:          2.3ms  ███████░░░░░░░░░░░░░  12%
  startup:                   1.8ms  ██████░░░░░░░░░░░░░░  10%
  hooks:                     1.5ms  █████░░░░░░░░░░░░░░░   8%
  functions:                 1.2ms  ████░░░░░░░░░░░░░░░░   6%
  widgets:                   0.9ms  ███░░░░░░░░░░░░░░░░░   5%

⚡ Special Timing:
  p10k-engine:               3.0ms  ████████░░░░░░░░░░░░  16%

📈 Total Bundle Time: 18.8ms

🐌 Slowest 10 Files:
   1. 12_completions.zsh                              1.8ms
   2. 99-zsh-syntax-highlighting.zsh                  1.5ms
   3. 20_plugins.zsh                                  1.2ms
   4. git.zsh                                         0.9ms
   5. 50_gitid.zsh                                    0.7ms

💡 Recommendations:
  • Core files take >20% of time - check core/12_completions.zsh
  • P10k theme engine takes >10% - ensure instant prompt is enabled

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
```bash

## Workflow

1. **First Run**: Builds instrumented profile bundle (~5-10 seconds)
2. **Profiling**: Launches new shell that collects timing data
3. **Report**: Displays performance report at shell startup
4. **Exit**: Type `exit` to return to original shell

## Timing Data Format

The `profile-timing.log` uses a simple pipe-delimited format:

```bash
TYPE|NAME|TIME_SECONDS
```bash

Types:

- `DIR` - Directory total time
- `FILE` - Individual file time
- `SPECIAL` - Special component (e.g., P10k engine)
- `BUNDLE` - Total bundle time

## Environment Variables

| Variable                | Description                                                           |
| ----------------------- | --------------------------------------------------------------------- |
| `ZSHAND_PROFILE_BUNDLE` | Set to `1` to enable profiling mode (set automatically by `zprofile`) |

## Technical Details

- Uses `$EPOCHREALTIME` for microsecond precision timing
- Instrumentation overhead is minimal (~1-2ms total)
- Profile bundle includes all files from full bundle
- P10k theme engine timing is captured in zshrc.zsh (post-bundle)

## Related Commands

- [`zfull`](zfull.md) - Build full bundle (non-instrumented)
- [`zprime`](zr.md) - Recompile framework bundles
- [`zrebuild`](zrebuild.md) - Force rebuild all bundles

## See Also

- [Profile Bundle Mode Plan](../../plans/profile-bundle-mode.md)
- [Performance Analysis](../../build/PERFORMANCE_ANALYSIS.md)