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

[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

[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

[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

[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

[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

[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

[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

[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

[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

[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

[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)

[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)

[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

[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

[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

[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

[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

[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

[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

[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

[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

[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

[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

[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

[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

[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

[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

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

Application Optimization

[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

[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

[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

[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

[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

[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

[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

[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
• Caching Strategies
• Frontend Optimization
• Memory Management
• Monitoring & Profiling