echoes-of-the-ash/REDIS_MONITORING.md

Redis Cache Monitoring Guide

Quick Methods to Monitor Redis Cache

1. API Endpoint (Easiest)

Access the cache stats endpoint:

# Using curl (replace with your auth token)
curl -H "Authorization: Bearer YOUR_TOKEN" http://localhost:8000/api/cache/stats

Response:

{
  "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

# 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

# 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:

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

# 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

# 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

# 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

# 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