Performance Configuration
Optimize GAPE for your server's size and hardware.
Performance Overview
GAPE is designed for minimal overhead, adding only 300-500 nanoseconds per packet on average. However, performance can be tuned based on your server's specific needs.
Async Processing
GAPE can run security checks asynchronously to avoid blocking the main server thread.
Enable Async Mode
When enabled, packet checks run on a separate thread pool, keeping the main game thread free for gameplay operations.
Thread Pool Size
Configure how many worker threads handle packet checks:
- Small servers (1-50 players): 2-4 threads
- Medium servers (50-500 players): 4-8 threads
- Large servers (500+ players): 8-16 threads
When to Use Async
- Enable if you have 50+ concurrent players
- Enable if you notice main thread lag during peak hours
- Disable for small servers where overhead is negligible
- Disable if you have limited CPU cores (< 4 cores)
Check Optimization
Selective Checking
Not all packets need all checks. GAPE intelligently applies only relevant checks to each packet type:
- Movement packets - Only position/NoCom checks
- Chat packets - Only chat spam and size checks
- Sign packets - NBT validation and sign exploit checks
- Book packets - NBT validation and book exploit checks
Check Priority
Checks run in priority order. Fast checks run first, expensive checks run last:
- Oversized packet (fastest, ~30ns)
- Rate limit (~50ns)
- Packet flood (~50ns)
- Custom payload flood (~100ns)
- Tab complete crash (~100ns)
- NoCom exploit (~150ns)
- Sign exploit (~200ns)
- Crasher detection (~200ns)
- Book exploit (~500ns, only on book packets)
Early Exit Optimization
If a check cancels a packet, remaining checks are skipped. Order checks by likelihood of triggering for best performance.
Caching
Player Data Cache
GAPE caches player-specific data to avoid repeated lookups:
- Permission checks (cached for 30 seconds)
- Bypass status (cached until permission change)
- Violation levels (in-memory, no disk I/O)
Packet Analysis Cache
Results of expensive packet analysis operations are cached:
- NBT parsing results (cached for identical NBT data)
- JSON validation results (cached for identical JSON)
- Regex pattern matches (cached for identical strings)
Cache Size Limits
Configure maximum cache sizes to balance memory usage vs performance:
- Small servers: 100-500 entries
- Medium servers: 500-2000 entries
- Large servers: 2000-10000 entries
Database Performance
Batch Writes
When using database logging, violations are batched instead of written immediately:
- Batch size: Write every N violations (default: 50)
- Batch interval: Write every N seconds (default: 30s)
- Async writes: All database writes happen off main thread
Connection Pooling
Maintain a pool of database connections for better performance:
- Minimum connections: Always keep N connections open
- Maximum connections: Never exceed N connections
- Connection timeout: Close idle connections after N seconds
Query Optimization
- Use prepared statements for all queries
- Index player UUID and timestamp columns
- Partition large tables by date
- Archive old violations to separate tables
Memory Management
Memory Footprint
GAPE's memory usage per player:
- Base tracking: ~200 bytes per player
- Violation history: ~50 bytes per check (500 bytes total)
- Packet rate data: ~300 bytes per player
- Total: ~1KB per player
Cleanup Intervals
GAPE automatically cleans up old data:
- Violation decay: Runs every 30 seconds
- Cache cleanup: Runs every 5 minutes
- Disconnected player data: Cleared after 10 minutes
Memory Limits
Set maximum memory usage for GAPE components:
- Cache size limit: Maximum MB for all caches
- Log buffer size: Maximum MB for log buffers
- Auto-cleanup threshold: Trigger cleanup when usage exceeds threshold
Network Optimization
Packet Buffering
Process packets in small batches instead of one-by-one:
- Reduces context switching overhead
- Improves cache locality
- Better CPU utilization
Zero-Copy Packet Reading
GAPE reads packet data directly from Netty buffers without copying when possible, reducing memory allocations and GC pressure.
Monitoring Performance
Built-in Metrics
GAPE tracks performance metrics automatically:
- Average check time per packet type
- Peak check times
- Packets processed per second
- Violations per second
- Thread pool utilization
- Cache hit/miss rates
Performance Commands
- /gape info - View current performance stats
- /gape debug performance - Detailed performance breakdown
Integration with Monitoring Tools
GAPE can export metrics to:
- Spark profiler
- Prometheus/Grafana
- Custom webhook endpoints
Performance Profiles
Maximum Performance
Lowest overhead, minimal features:
- Async mode disabled
- Minimal logging (threshold only)
- No database logging
- Small caches
- Fast checks only
Balanced (Recommended)
Best performance/protection ratio:
- Async mode enabled for 50+ players
- Threshold logging
- SQLite database with batch writes
- Medium caches
- All checks enabled
Maximum Protection
All features enabled, higher overhead:
- Async mode enabled
- Verbose logging
- MySQL database with real-time writes
- Large caches
- All checks enabled with low thresholds
Troubleshooting Performance Issues
High CPU Usage
- Enable async mode
- Reduce thread pool size if CPU-limited
- Disable expensive checks (book exploit, NBT validation)
- Increase cache sizes to reduce repeated work
- Check for violation spam (indicates ongoing attack)
High Memory Usage
- Reduce cache sizes
- Decrease violation history retention
- Enable more aggressive cleanup
- Switch from MySQL to SQLite
- Disable database logging entirely
Main Thread Lag
- Enable async mode immediately
- Increase thread pool size
- Reduce logging verbosity
- Disable real-time database writes
- Check if specific checks are taking too long