Rustelo/book/configuration/performance.md

# Performance Configuration

Rustelo provides extensive performance tuning options to optimize your application for different workloads and deployment scenarios. This chapter covers how to configure performance-related settings, optimize resource usage, and monitor application performance.

## Overview

Performance optimization in Rustelo covers:

- **Server Configuration**: Worker threads, connection limits, and request handling
- **Database Optimization**: Connection pooling, query optimization, and caching
- **Memory Management**: Heap size, garbage collection, and memory pools
- **Caching Systems**: Multi-level caching strategies and cache invalidation
- **Asset Optimization**: Static file serving, compression, and CDN integration
- **Monitoring & Profiling**: Performance metrics and bottleneck identification

## Server Performance Configuration

### Worker Thread Configuration

```toml
[server.performance]
workers = 8                    # Number of worker threads (default: CPU cores)
worker_max_blocking_threads = 32  # Max blocking threads per worker
worker_thread_stack_size = 2097152  # Stack size per thread (2MB)
worker_thread_keep_alive = 60      # Keep-alive time for idle threads
max_connections = 10000            # Maximum concurrent connections
connection_timeout = 30            # Connection timeout in seconds
keep_alive_timeout = 65            # Keep-alive timeout
```

### Request Handling

```toml
[server.requests]
max_request_size = 52428800       # 50MB max request size
max_header_size = 32768           # 32KB max header size
max_uri_length = 8192             # 8KB max URI length
request_timeout = 30              # Request timeout in seconds
slow_request_threshold = 1000     # Log slow requests over 1 second
max_concurrent_requests = 1000    # Max concurrent requests
```

### Connection Management

```toml
[server.connections]
tcp_nodelay = true                # Disable Nagle's algorithm
tcp_keepalive = true             # Enable TCP keepalive
keepalive_time = 7200            # Keepalive time (2 hours)
keepalive_interval = 75          # Keepalive probe interval
keepalive_probes = 9             # Number of keepalive probes
reuse_port = true                # Enable SO_REUSEPORT
backlog = 1024                   # Listen backlog queue size
```

## Database Performance Configuration

### Connection Pool Optimization

```toml
[database.performance]
max_connections = 20             # Maximum pool size
min_connections = 5              # Minimum pool size
acquire_timeout = 30             # Connection acquire timeout
idle_timeout = 600               # Idle connection timeout
max_lifetime = 1800              # Maximum connection lifetime
test_before_acquire = false      # Test connections before use
```

### Query Optimization

```toml
[database.queries]
statement_timeout = 30000        # Query timeout in milliseconds
slow_query_threshold = 1000      # Log slow queries over 1 second
enable_query_cache = true        # Enable query result caching
query_cache_size = 134217728     # Query cache size (128MB)
query_cache_ttl = 300           # Query cache TTL in seconds
prepared_statement_cache_size = 256  # Prepared statement cache size
```

### Database-Specific Optimizations

#### PostgreSQL

```toml
[database.postgresql]
shared_buffers = "256MB"         # Shared buffer size
effective_cache_size = "1GB"     # Effective cache size
work_mem = "4MB"                 # Work memory per query
maintenance_work_mem = "64MB"    # Maintenance work memory
checkpoint_completion_target = 0.7  # Checkpoint completion target
wal_buffers = "16MB"             # WAL buffer size
default_statistics_target = 100  # Statistics target
random_page_cost = 1.1           # Random page cost
```

#### SQLite

```toml
[database.sqlite]
journal_mode = "WAL"             # Write-Ahead Logging
synchronous = "NORMAL"           # Synchronous mode
cache_size = 10000               # Page cache size
temp_store = "memory"            # Temporary storage in memory
mmap_size = 268435456            # Memory-mapped I/O size (256MB)
page_size = 4096                 # Page size in bytes
```

## Memory Management

### Heap Configuration

```toml
[memory]
initial_heap_size = 134217728    # Initial heap size (128MB)
max_heap_size = 2147483648       # Maximum heap size (2GB)
gc_threshold = 0.75              # GC threshold (75% of heap)
gc_trigger_interval = 60         # GC trigger interval in seconds
```

### Memory Pools

```toml
[memory.pools]
buffer_pool_size = 67108864      # Buffer pool size (64MB)
string_pool_size = 16777216      # String pool size (16MB)
object_pool_size = 33554432      # Object pool size (32MB)
connection_pool_memory = 8388608  # Connection pool memory (8MB)
```

### Memory Monitoring

```toml
[memory.monitoring]
track_allocations = true         # Track memory allocations
memory_usage_threshold = 0.8     # Alert when memory usage > 80%
enable_memory_profiling = false  # Enable memory profiling (dev only)
memory_leak_detection = true     # Enable memory leak detection
```

## Caching Configuration

### Multi-Level Caching

```toml
[cache]
enabled = true
default_ttl = 3600               # Default cache TTL (1 hour)
max_memory_size = 268435456      # Max memory cache size (256MB)
cleanup_interval = 300           # Cache cleanup interval (5 minutes)
compression_enabled = true       # Enable cache compression
compression_threshold = 1024     # Compress items larger than 1KB
```

### L1 Cache (In-Memory)

```toml
[cache.l1]
enabled = true
max_entries = 10000              # Maximum cache entries
eviction_policy = "lru"          # Eviction policy: lru, lfu, fifo
segment_count = 16               # Number of cache segments
expire_after_write = 3600        # Expire after write (1 hour)
expire_after_access = 1800       # Expire after access (30 minutes)
```

### L2 Cache (Redis)

```toml
[cache.l2]
enabled = true
redis_url = "${REDIS_URL}"
database = 0                     # Redis database number
key_prefix = "rustelo:"          # Cache key prefix
connection_pool_size = 10        # Redis connection pool size
connection_timeout = 5           # Redis connection timeout
command_timeout = 5              # Redis command timeout
```

### Application-Level Caching

```toml
[cache.application]
page_cache_enabled = true        # Enable page caching
page_cache_ttl = 1800           # Page cache TTL (30 minutes)
api_cache_enabled = true         # Enable API response caching
api_cache_ttl = 300             # API cache TTL (5 minutes)
template_cache_enabled = true    # Enable template caching
static_file_cache_enabled = true # Enable static file caching
```

## Asset Optimization

### Static File Serving

```toml
[assets]
serve_static_files = true        # Serve static files
static_file_cache_control = "public, max-age=31536000"  # 1 year cache
enable_etag = true               # Enable ETag headers
enable_last_modified = true      # Enable Last-Modified headers
enable_range_requests = true     # Enable range requests
```

### Compression

```toml
[assets.compression]
enabled = true
algorithms = ["gzip", "deflate", "br"]  # Compression algorithms
compression_level = 6            # Compression level (1-9)
min_file_size = 1024            # Minimum file size to compress
compress_types = [               # MIME types to compress
    "text/html",
    "text/css",
    "text/javascript",
    "application/javascript",
    "application/json",
    "text/xml",
    "application/xml"
]
```

### CDN Integration

```toml
[assets.cdn]
enabled = false                  # Enable CDN
cdn_url = "https://cdn.example.com"  # CDN base URL
cdn_paths = ["/static", "/assets"]   # Paths to serve from CDN
cache_bust_enabled = true        # Enable cache busting
cache_bust_strategy = "timestamp"  # Strategy: timestamp, hash, version
```

## Performance Monitoring

### Metrics Collection

```toml
[performance.metrics]
enabled = true
collection_interval = 15        # Metrics collection interval (seconds)
retention_period = 2592000      # Metrics retention (30 days)
high_resolution_metrics = true  # Enable high-resolution metrics
```

### Response Time Monitoring

```toml
[performance.response_times]
track_percentiles = true         # Track response time percentiles
percentiles = [50, 75, 90, 95, 99, 99.9]  # Percentiles to track
slow_request_threshold = 1000    # Slow request threshold (1 second)
very_slow_request_threshold = 5000  # Very slow request threshold (5 seconds)
```

### Resource Monitoring

```toml
[performance.resources]
monitor_cpu = true               # Monitor CPU usage
monitor_memory = true            # Monitor memory usage
monitor_disk = true              # Monitor disk I/O
monitor_network = true           # Monitor network I/O
monitor_connections = true       # Monitor connection count
```

## Profiling Configuration

### CPU Profiling

```toml
[profiling.cpu]
enabled = false                  # Enable CPU profiling (dev/staging only)
sampling_interval = 10000        # Sampling interval in microseconds
profile_duration = 60            # Profile duration in seconds
output_format = "flamegraph"     # Output format: flamegraph, callgrind
```

### Memory Profiling

```toml
[profiling.memory]
enabled = false                  # Enable memory profiling (dev/staging only)
track_allocations = true         # Track individual allocations
heap_profiling = true            # Enable heap profiling
leak_detection = true            # Enable memory leak detection
```

### Database Profiling

```toml
[profiling.database]
enabled = false                  # Enable database profiling
log_all_queries = false          # Log all database queries
log_slow_queries = true          # Log slow queries only
explain_slow_queries = true      # Add EXPLAIN to slow queries
query_plan_cache = true          # Cache query execution plans
```

## Environment-Specific Performance

### Development Environment

```toml
[performance.development]
optimize_for_development = true  # Enable development optimizations
hot_reload_enabled = true        # Enable hot reloading
debug_mode = true                # Enable debug mode
profiling_enabled = true         # Enable profiling
reduced_caching = true           # Reduce caching for development
```

### Production Environment

```toml
[performance.production]
optimize_for_production = true   # Enable production optimizations
aggressive_caching = true        # Enable aggressive caching
connection_pooling = true        # Enable connection pooling
jit_compilation = true           # Enable JIT compilation
gc_optimization = true           # Enable garbage collection optimization
```

## Load Testing Configuration

### Test Parameters

```toml
[load_testing]
max_virtual_users = 1000         # Maximum virtual users
ramp_up_time = 60               # Ramp-up time in seconds
test_duration = 300             # Test duration in seconds
think_time = 1                  # Think time between requests
```

### Performance Targets

```toml
[load_testing.targets]
response_time_p95 = 500         # 95th percentile response time (ms)
response_time_p99 = 1000        # 99th percentile response time (ms)
throughput_rps = 1000           # Requests per second
error_rate_threshold = 0.01     # Maximum error rate (1%)
cpu_usage_threshold = 0.8       # Maximum CPU usage (80%)
memory_usage_threshold = 0.8    # Maximum memory usage (80%)
```

## Performance Optimization Strategies

### Database Optimization

```toml
[optimization.database]
enable_query_optimization = true
index_optimization = true
query_caching = true
connection_pooling = true
read_replicas = false
database_sharding = false
```

### Application Optimization

```toml
[optimization.application]
lazy_loading = true              # Enable lazy loading
async_processing = true          # Enable async processing
batch_operations = true          # Enable batch operations
response_streaming = true        # Enable response streaming
request_coalescing = true        # Enable request coalescing
```

### System Optimization

```toml
[optimization.system]
kernel_bypass = false            # Enable kernel bypass (advanced)
numa_awareness = true            # Enable NUMA awareness
cpu_affinity = false            # Enable CPU affinity
disk_io_optimization = true     # Enable disk I/O optimization
network_optimization = true     # Enable network optimization
```

## Monitoring and Alerting

### Performance Alerts

```toml
[alerts.performance]
enabled = true
response_time_threshold = 2000   # Response time alert threshold (2 seconds)
throughput_threshold = 100       # Throughput alert threshold (100 RPS)
error_rate_threshold = 0.05      # Error rate alert threshold (5%)
memory_usage_threshold = 0.9     # Memory usage alert threshold (90%)
cpu_usage_threshold = 0.9        # CPU usage alert threshold (90%)
```

### Health Checks

```toml
[health_checks]
enabled = true
check_interval = 30              # Health check interval (seconds)
timeout = 5                      # Health check timeout (seconds)
failure_threshold = 3            # Consecutive failures before alert
```

## Benchmarking Configuration

### Benchmark Settings

```toml
[benchmarking]
enabled = false                  # Enable benchmarking
benchmark_duration = 60          # Benchmark duration (seconds)
warmup_duration = 10             # Warmup duration (seconds)
concurrency_levels = [1, 10, 100, 1000]  # Concurrency levels to test
```

### Performance Baselines

```toml
[benchmarking.baselines]
response_time_baseline = 100     # Response time baseline (ms)
throughput_baseline = 1000       # Throughput baseline (RPS)
memory_baseline = 134217728      # Memory baseline (128MB)
cpu_baseline = 0.5               # CPU baseline (50%)
```

## Troubleshooting Performance Issues

### Common Performance Problems

1. **High Response Times**
   - Check database query performance
   - Review caching configuration
   - Monitor resource usage
   - Analyze request patterns

2. **Memory Issues**
   - Monitor memory usage patterns
   - Check for memory leaks
   - Review garbage collection settings
   - Optimize memory allocation

3. **CPU Bottlenecks**
   - Profile CPU usage
   - Check for inefficient algorithms
   - Review worker thread configuration
   - Optimize hot code paths

4. **Database Performance**
   - Analyze slow queries
   - Check connection pool settings
   - Review database configuration
   - Optimize indexes

### Performance Debugging

```toml
[debugging.performance]
enable_detailed_logging = true   # Enable detailed performance logging
request_tracing = true           # Enable request tracing
sql_query_logging = true         # Enable SQL query logging
memory_tracking = true           # Enable memory tracking
cpu_profiling = true             # Enable CPU profiling
```

## Best Practices

### Performance Optimization Guidelines

1. **Measure Before Optimizing**
   - Establish performance baselines
   - Use profiling tools
   - Monitor key metrics
   - Identify bottlenecks

2. **Optimize Incrementally**
   - Make small, measurable changes
   - Test each optimization
   - Monitor impact
   - Rollback if necessary

3. **Cache Strategically**
   - Cache frequently accessed data
   - Use appropriate cache levels
   - Implement cache invalidation
   - Monitor cache hit rates

4. **Database Optimization**
   - Use appropriate indexes
   - Optimize query structure
   - Configure connection pooling
   - Monitor slow queries

### Performance Testing

```toml
[testing.performance]
automated_testing = true         # Enable automated performance testing
regression_testing = true       # Enable performance regression testing
load_testing = true             # Enable load testing
stress_testing = true           # Enable stress testing
```

## Performance Checklist

### Pre-Production Performance Review

- [ ] Database queries optimized
- [ ] Appropriate indexes created
- [ ] Connection pooling configured
- [ ] Caching strategy implemented
- [ ] Static assets optimized
- [ ] Compression enabled
- [ ] Memory limits configured
- [ ] Worker threads optimized
- [ ] Performance monitoring enabled
- [ ] Load testing completed
- [ ] Performance baselines established
- [ ] Alerting configured

## Next Steps

- [Database Optimization](../performance/database.md)
- [Caching Strategies](../performance/caching.md)
- [Frontend Optimization](../performance/frontend.md)
- [Memory Management](../performance/memory.md)
- [Monitoring & Profiling](../performance/monitoring.md)