FlexLove/profiling/reports/README.md

Profiling Reports

This directory contains performance profiling reports generated by the FlexLöve profiling system.

Directory Structure

Reports are organized by profile name:

reports/
├── animation_stress/
│   ├── latest.md          # Most recent report (Markdown)
│   ├── latest.json        # Most recent report (JSON)
│   ├── 2025-11-20_10-30-00.md
│   └── 2025-11-20_10-30-00.json
├── event_stress/
│   ├── latest.md
│   └── latest.json
└── ...

Report Format

Each test run generates two files:

• <timestamp>.md - Human-readable Markdown report with formatted tables
• <timestamp>.json - Machine-readable JSON data for programmatic analysis
• latest.md - Always contains the most recent report for quick access
• latest.json - Most recent JSON data

Report Contents

FPS Statistics

• Average FPS: Mean frames per second across the entire test
• Median FPS: Middle value of all FPS measurements
• 1% Worst FPS: The FPS at which 1% of frames performed at or below this level (useful for identifying stutters)
• 0.1% Worst FPS: The FPS at which 0.1% of frames performed at or below this level (worst case performance)

Frame Time Statistics

• Average: Mean frame time in milliseconds
• Median: Middle value of all frame time measurements
• 95th/99th/99.9th Percentile: Frame times that 95%/99%/99.9% of frames completed under

Memory Usage

• Average: Mean memory usage across the test
• Peak: Maximum memory used during the test
• 95th/99th/99.9th Percentile: Memory usage levels that 95%/99%/99.9% of samples were under

How to Generate Reports

Automatic (on exit)

Reports are automatically saved when you:

• Press ESC to return to the menu
• Quit the profiling application

Manual

While a profile is running, press S to manually save a report without stopping the test.

Interpreting Results

Good Performance Indicators

• Average FPS close to target (60 FPS for most applications)
• Small difference between average and 1% worst FPS
• Low 99.9th percentile frame times (< 20ms for 60 FPS)
• Stable memory usage without continuous growth

Performance Issues to Watch For

• Large gap between average and 1%/0.1% worst FPS (indicates frame drops/stutters)
• High 99.9th percentile frame times (indicates occasional severe lag spikes)
• Continuously growing memory usage (indicates memory leak)
• High memory peak compared to average (indicates GC pressure)