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