Commit

REDIS_MONITORING.md

@@ -0,0 +1,180 @@
+# Redis Cache Monitoring Guide
+
+## Quick Methods to Monitor Redis Cache
+
+### 1. **API Endpoint (Easiest)**
+
+Access the cache stats endpoint:
+
+```bash
+# Using curl (replace with your auth token)
+curl -H "Authorization: Bearer YOUR_TOKEN" http://localhost:8000/api/cache/stats
+```
+
+**Response:**
+```json
+{
+  "enabled": true,
+  "redis_stats": {
+    "total_commands_processed": 15234,
+    "ops_per_second": 12,
+    "connected_clients": 8
+  },
+  "cache_performance": {
+    "hits": 8542,
+    "misses": 1234,
+    "total_requests": 9776,
+    "hit_rate_percent": 87.38
+  },
+  "current_user": {
+    "inventory_cached": true,
+    "player_id": 1
+  }
+}
+```
+
+**What to look for:**
+- `hit_rate_percent`: Should be 70-90% for good cache performance
+- `inventory_cached`: Shows if your inventory is currently in cache
+- `ops_per_second`: Redis operations per second
+
+---
+
+### 2. **Redis CLI - Real-time Monitoring**
+
+```bash
+# Connect to Redis container
+docker exec -it echoes_of_the_ashes_redis redis-cli
+
+# View detailed statistics
+INFO stats
+
+# Monitor all commands in real-time (shows every cache hit/miss)
+MONITOR
+
+# View all inventory cache keys
+KEYS player:*:inventory
+
+# Check if specific player's inventory is cached
+EXISTS player:1:inventory
+
+# Get TTL (time to live) of a cached inventory
+TTL player:1:inventory
+
+# View cached inventory data
+GET player:1:inventory
+```
+
+---
+
+### 3. **Application Logs**
+
+```bash
+# View all cache-related logs
+docker logs echoes_of_the_ashes_api -f | grep -i "redis\|cache"
+
+# View only cache failures
+docker logs echoes_of_the_ashes_api -f | grep "cache.*failed"
+```
+
+---
+
+### 4. **Redis Commander (Web UI)**
+
+Add Redis Commander to your docker-compose.yml for a web-based UI:
+
+```yaml
+redis-commander:
+  image: rediscommander/redis-commander:latest
+  environment:
+    - REDIS_HOSTS=local:echoes_of_the_ashes_redis:6379
+  ports:
+    - "8081:8081"
+  depends_on:
+    - echoes_of_the_ashes_redis
+```
+
+Then access: http://localhost:8081
+
+---
+
+## Understanding Cache Metrics
+
+### Hit Rate
+- **90%+**: Excellent - Most requests served from cache
+- **70-90%**: Good - Cache is working well
+- **50-70%**: Fair - Consider increasing TTL or investigating invalidation
+- **<50%**: Poor - Cache may not be effective
+
+### Inventory Cache Keys
+- Format: `player:{player_id}:inventory`
+- TTL: 600 seconds (10 minutes)
+- Invalidated on: add/remove items, equip/unequip, property updates
+
+### Expected Behavior
+1. **First inventory load**: Cache MISS → Database query → Cache write
+2. **Subsequent loads**: Cache HIT → Fast response (~1-3ms)
+3. **After mutation** (pickup item): Cache invalidated → Next load is MISS
+4. **After 10 minutes**: Cache expires → Next load is MISS
+
+---
+
+## Testing Cache Performance
+
+### Test 1: Verify Caching Works
+```bash
+# 1. Load inventory (should be cache MISS)
+curl -H "Authorization: Bearer TOKEN" http://localhost:8000/api/game/state
+
+# 2. Load again immediately (should be cache HIT - much faster)
+curl -H "Authorization: Bearer TOKEN" http://localhost:8000/api/game/state
+
+# 3. Check stats
+curl -H "Authorization: Bearer TOKEN" http://localhost:8000/api/cache/stats
+```
+
+### Test 2: Verify Invalidation Works
+```bash
+# 1. Load inventory (cache HIT if already loaded)
+curl -H "Authorization: Bearer TOKEN" http://localhost:8000/api/game/state
+
+# 2. Pick up an item (invalidates cache)
+curl -X POST -H "Authorization: Bearer TOKEN" http://localhost:8000/api/game/pickup_item
+
+# 3. Load inventory again (should be cache MISS)
+curl -H "Authorization: Bearer TOKEN" http://localhost:8000/api/game/state
+```
+
+---
+
+## Troubleshooting
+
+### Cache Not Working
+```bash
+# Check if Redis is running
+docker ps | grep redis
+
+# Check Redis connectivity
+docker exec -it echoes_of_the_ashes_redis redis-cli PING
+# Should return: PONG
+
+# Check application logs for errors
+docker logs echoes_of_the_ashes_api | grep -i "redis"
+```
+
+### Low Hit Rate
+- Check if cache TTL is too short (currently 10 minutes)
+- Verify invalidation isn't too aggressive
+- Monitor which operations are causing cache misses
+
+### High Memory Usage
+```bash
+# Check Redis memory usage
+docker exec -it echoes_of_the_ashes_redis redis-cli INFO memory
+
+# View all cached keys
+docker exec -it echoes_of_the_ashes_redis redis-cli KEYS "*"
+
+# Clear all cache (use with caution!)
+docker exec -it echoes_of_the_ashes_redis redis-cli FLUSHALL
+```