Performance Tuning Guide

Optimize GAPE for maximum performance on your server.

Quick Wins

Start here for immediate performance improvements:

1. Enable Async Processing

Run security checks off the main thread:

• Enable async mode in config
• Set thread pool size to 4-8 threads
• Immediate reduction in main thread lag

2. Optimize Logging

Reduce logging overhead:

• Set log level to "threshold only"
• Disable console logging, use file only
• Enable log batching
• Set log rotation to daily

3. Disable Unused Checks

If certain exploits aren't a concern:

• Disable checks you don't need
• Keep critical checks: Crasher, Tab Complete, Oversized Packet
• Each disabled check saves ~50-500ns per packet

Server Size Optimization

Small Servers (1-50 Players)

• Async mode: Disabled (overhead not worth it)
• Thread pool: N/A
• Cache size: 100-500 entries
• Database: SQLite with batch writes
• Logging: Threshold only

Medium Servers (50-500 Players)

• Async mode: Enabled
• Thread pool: 4-8 threads
• Cache size: 500-2000 entries
• Database: MySQL with batch writes
• Logging: Threshold only, async writes

Large Servers (500-1000+ Players)

• Async mode: Enabled
• Thread pool: 8-16 threads
• Cache size: 2000-10000 entries
• Database: MySQL with large batch sizes
• Logging: Async, compressed, aggressive rotation

CPU Optimization

Reduce Per-Packet Overhead

• Disable expensive checks: Book Exploit, NBT validation if not needed
• Increase batch sizes: Process packets in larger batches
• Lower cache hit rate checks: Review which caches are actually helping

Thread Pool Tuning

• CPU cores - 2 = max threads: Leave cores for Minecraft
• Monitor thread utilization: Use /gape debug performance
• Too many threads: Context switching overhead
• Too few threads: Packets queue up

Check Ordering

Run fast checks first to exit early:

1. Oversized Packet (~30ns)
2. Rate Limit (~50ns)
3. Packet Flood (~50ns)
4. Command Spam (~50ns)
5. Custom Payload (~100ns)
6. Tab Complete (~100ns)
7. NoCom (~150ns)
8. Sign Exploit (~200ns)
9. Crasher (~200ns)
10. Book Exploit (~500ns)

Memory Optimization

Cache Management

• Right-size caches: Monitor hit rates, adjust sizes
• Aggressive cleanup: Clear stale entries every 1-2 minutes
• Limit per-player data: Cap violation history length

Database Tuning

• Large batch sizes: Write 100-500 violations at once
• Connection pooling: Reuse database connections
• Async writes: Never block main thread for database
• Purge old data: Delete violations older than 30 days

Log Management

• Compress old logs: Save 80-90% disk space
• Aggressive rotation: New log daily or at 10MB
• Delete old logs: Keep only 7-14 days
• Disable verbose logging: Threshold-only in production

Network Optimization

Packet Buffering

• Process packets in small batches (5-10 at a time)
• Reduces context switching
• Better CPU cache utilization

Zero-Copy Reading

• Read directly from Netty buffers when possible
• Avoid copying packet data unnecessarily
• Reduces memory allocations and GC pressure

Monitoring Performance

Built-in Metrics

Use GAPE's performance tracking:

• /gape info: Overview of current performance
• /gape debug performance: Detailed breakdown per check
• Track average check time per packet type
• Monitor thread pool utilization
• Check cache hit/miss rates

External Profiling

• Spark: CPU profiling to find hotspots
• Timings: Paper's built-in performance monitoring
• VisualVM: Memory profiling and GC analysis

What to Monitor

• Main thread tick time: Should stay under 50ms
• GAPE thread pool: Utilization should be 60-80%
• Memory usage: GAPE should use under 100MB for 1000 players
• GC frequency: GAPE shouldn't cause GC spikes

Configuration Templates

Maximum Performance (Minimal Protection)

• Only critical checks enabled (Crasher, Tab Complete, Oversized)
• No async processing
• Minimal logging
• No database
• Small caches

Balanced (Recommended)

• All checks enabled with default thresholds
• Async processing for 50+ players
• Threshold-only logging
• SQLite or MySQL with batching
• Medium caches

Maximum Protection (Higher Overhead)

• All checks enabled with strict thresholds
• Async processing enabled
• Verbose logging
• MySQL with real-time writes
• Large caches
• Heuristic analysis enabled

Troubleshooting Performance

Main Thread Lag

If server TPS drops after installing GAPE:

• Enable async mode immediately
• Increase thread pool size
• Disable Book Exploit and NBT validation temporarily
• Set logging to async mode
• Profile with Spark to confirm GAPE is the cause

High CPU Usage

• Reduce thread pool size if CPU-limited
• Disable expensive checks
• Increase cache sizes to reduce repeated work
• Check for active attack causing high packet rates

Memory Leaks

• Enable aggressive cache cleanup
• Reduce cache sizes
• Clear violation history more frequently
• Check for database connection leaks

Advanced Tuning

JVM Flags

Optimize Java for GAPE:

• Use G1GC for servers with 4GB+ RAM
• Allocate sufficient heap space
• Enable aggressive GC for real-time systems

Custom Check Priorities

Reorder checks based on your attack patterns:

• Put most frequently triggered checks first
• Fast checks before slow checks
• High-value checks before low-value

Dynamic Scaling

• Increase thread pool during peak hours
• Reduce logging verbosity during high load
• Batch database writes during attacks

Benchmarking

Baseline Test

• Measure server TPS without GAPE
• Install GAPE with default config
• Measure TPS again
• Difference should be under 1-2 TPS for 100 players

Load Testing

• Simulate high player counts (bot testing)
• Measure packet processing latency
• Monitor thread pool saturation
• Track memory usage over time

Best Practices

• Start with default configuration
• Enable async mode for 50+ players
• Monitor performance for 24-48 hours before tuning
• Make one change at a time and measure impact
• Keep critical checks enabled even if performance-sensitive
• Profile before optimizing - don't guess