Add metrics for performance

CMakeLists.txt

@@ -86,6 +86,7 @@ if(BUILD_TESTS)
         tests/test_version.cpp
         tests/test_threading.cpp
         tests/test_disk_backing.cpp
+        tests/test_metrics.cpp
     )
 
     target_link_libraries(ghostmem_tests ghostmem)

README.md

@@ -298,6 +298,41 @@ cd build
 ./ghostmem_demo
 ```
 
+### Running Tests
+
+The project includes comprehensive test suites for correctness and performance:
+
+**Run all tests:**
+```batch
+# Windows
+cd build\Release
+ghostmem_tests.exe
+
+# Linux
+cd build
+./ghostmem_tests
+```
+
+**Run performance metrics tests only:**
+```batch
+# Windows
+run_metrics.bat
+
+# Linux
+chmod +x run_metrics.sh
+./run_metrics.sh
+```
+
+The metrics tests measure:
+- **Compression ratios** for different data types (text, sparse data, random data)
+- **Memory savings** achieved through compression (typically 60-95%)
+- **Performance overhead** compared to standard C++ allocation (3-5x slowdown)
+- **Speed comparisons** between malloc and GhostMem operations
+
+Results are saved to `metrics_results/` with timestamps for comparison across versions.
+
+For detailed information about performance metrics and how to use them for improvements, see [docs/PERFORMANCE_METRICS.md](docs/PERFORMANCE_METRICS.md).
+
 ## Roadmap
 
 ### 🐧 **Linux & Cross-Platform Support**
@@ -316,12 +351,13 @@ cd build
   - Compression/decompression cycles
   - LRU eviction policy
   - Page fault handling
+- ✅ Performance metrics tests → **[tests/test_metrics.cpp](tests/test_metrics.cpp)**
+  - Compression ratio measurements
+  - Memory savings estimation
+  - Speed comparisons (malloc vs GhostMem)
+  - Access pattern performance
 - [ ] Integration tests with real applications
 - [ ] Stress tests (concurrent access, high memory pressure)
-- [ ] Performance benchmarks
-  - Compression ratios for different data types
-  - Latency measurements
-  - Throughput tests
 - [ ] Memory leak detection and validation
 - ✅ CI/CD pipeline (GitHub Actions)
 
@@ -338,6 +374,11 @@ cd build
   - Multi-threading guarantees and patterns
   - Performance in concurrent scenarios
   - Platform-specific considerations
+- ✅ Performance metrics guide → **[docs/PERFORMANCE_METRICS.md](docs/PERFORMANCE_METRICS.md)**
+  - Understanding compression ratios
+  - Performance benchmarking methodology
+  - How to use metrics for improvements
+  - KPIs and optimization targets
 - [ ] Performance tuning guide
   - Choosing optimal `MAX_PHYSICAL_PAGES`
   - Workload-specific configurations

docs/METRICS_SUMMARY.md

@@ -0,0 +1,150 @@
+# GhostMem Metrics Test Summary
+
+## Quick Reference
+
+### Running Metrics Tests
+
+**Windows:**
+```batch
+run_metrics.bat
+```
+
+**Linux:**
+```bash
+./run_metrics.sh
+```
+
+**Manual:**
+```bash
+cd build/Release    # Windows
+./build             # Linux
+./ghostmem_tests    # Runs all tests including metrics
+```
+
+## Test Categories
+
+### 1. Compression Metrics (4 tests)
+- `CompressionMetrics_HighlyCompressibleData` - Measures best-case compression (repeating patterns)
+- `CompressionMetrics_TextData` - Realistic text compression ratios
+- `CompressionMetrics_RandomData` - Worst-case incompressible data
+- `CompressionMetrics_SparseData` - Sparse matrix/zero-heavy data compression
+
+### 2. Performance Metrics (4 tests)
+- `PerformanceMetrics_AllocationSpeed` - malloc vs GhostMem allocation time
+- `PerformanceMetrics_AccessPatterns_Sequential` - Linear array traversal speed
+- `PerformanceMetrics_AccessPatterns_Random` - Random access performance
+- `PerformanceMetrics_CompressionCycleOverhead` - Compress/decompress cycle cost
+
+### 3. Memory Savings (1 test)
+- `MemoryMetrics_EstimatedSavings` - Theoretical RAM savings for different data types
+
+## Current Baseline Results (v0.10.0)
+
+### Compression Ratios
+| Data Type | Original Size | Expected Compression | Savings |
+|-----------|--------------|---------------------|---------|
+| Highly compressible | 40 KB | 50:1 to 100:1 | ~93% |
+| Text data | 40 KB | 5:1 to 10:1 | ~80.7% |
+| Sparse data | 40 KB | 100:1+ | ~94% |
+| Random data | 40 KB | 1:1 (none) | -5% (overhead) |
+
+### Performance Overhead
+| Test | Standard C++ | GhostMem | Slowdown |
+|------|-------------|----------|----------|
+| Allocation | 0.0003 ms | 0.0128 ms | **44x** ⚠️ |
+| Sequential access | 0.0135 ms | 0.0697 ms | **5.16x** ⚠️ |
+| Random access | 0.0221 ms | 0.0839 ms | **3.8x** ✓ |
+
+### Memory Savings Estimation
+For 400 KB virtual memory with 20 KB physical limit:
+
+| Scenario | RAM Savings | Recommendation |
+|----------|-------------|----------------|
+| Highly compressible | 93% | ✅ Excellent |
+| Text data | 80.7% | ✅ Excellent |
+| Sparse data | 94% | ✅ Excellent |
+| Mixed data | 61.7% | ✓ Good |
+| Random data | -5% | ⛔ Not suitable |
+
+## Using Metrics for Development
+
+### Before Making Changes
+1. Run metrics: `run_metrics.bat`
+2. Save baseline: Copy result from `metrics_results/` folder
+3. Note key numbers: slowdown factors, compression ratios
+
+### After Making Changes
+1. Rebuild: `cd build && cmake --build . --config Release`
+2. Run metrics: `run_metrics.bat`
+3. Compare results: Check for improvements/regressions
+
+### Key Numbers to Watch
+- **Allocation slowdown**: Target <10x (currently 44x)
+- **Sequential access**: Target <2x (currently 5.16x)
+- **Random access**: Target <3x (currently 3.8x - ✓ good!)
+- **Compression ratios**: Higher is better
+- **Memory savings**: >70% is excellent
+
+## Optimization Opportunities
+
+### High Priority
+1. **Allocation overhead (44x slowdown)**
+   - Batch page fault setup
+   - Reduce virtual memory reservation overhead
+   - Pool pre-allocated pages
+
+2. **Sequential access (5x slowdown)**
+   - Optimize page fault handler
+   - Reduce mutex contention
+   - Prefetch adjacent pages
+
+### Medium Priority
+3. **Compression efficiency**
+   - Tune LZ4 compression level
+   - Experiment with different compressors
+   - Adaptive compression based on data type
+
+4. **LRU optimization**
+   - Better eviction heuristics
+   - Predict access patterns
+   - Multi-level caching
+
+### Low Priority
+5. **Memory overhead**
+   - Reduce backing_store overhead
+   - Compress in parallel
+   - Batch compression operations
+
+## Adding Custom Metrics
+
+Edit [tests/test_metrics.cpp](../tests/test_metrics.cpp):
+
+```cpp
+TEST(CustomMetric_YourTest) {
+    std::cout << "\n=== Your Custom Test ===\n";
+
+    auto start = std::chrono::high_resolution_clock::now();
+
+    // Your test code here
+
+    auto end = std::chrono::high_resolution_clock::now();
+    double time_ms = std::chrono::duration<double, std::milli>(end - start).count();
+
+    std::cout << "Result: " << time_ms << " ms\n";
+}
+```
+
+Then rebuild and run tests.
+
+## Integration with CI/CD
+
+The metrics tests run automatically in GitHub Actions on every push. Check the "Build and Test" workflow results to see if performance has regressed.
+
+Future enhancement: Add performance regression detection that fails the build if metrics worsen significantly.
+
+## Questions?
+
+- Full documentation: [docs/PERFORMANCE_METRICS.md](PERFORMANCE_METRICS.md)
+- API reference: [docs/API_REFERENCE.md](API_REFERENCE.md)
+- Integration guide: [docs/INTEGRATION_GUIDE.md](INTEGRATION_GUIDE.md)
+- Contact: kalski.swen@gmail.com