Sentinal Redis

Monitor Redis server health, memory, performance, and BullMQ queues. Check queue depths, inspect failed jobs, analyze slow queries, and diagnose issues.

Monitor Redis server health, BullMQ queues, memory, and performance from any messaging channel. Ask questions in plain English — get actionable diagnostics.

When to Use

✅ USE this skill when:

• User asks about Redis server health, status, or info
• User wants to check memory usage or diagnose OOM issues
• User asks about BullMQ queue depths, failed jobs, or stuck workers
• User wants to inspect slow queries or latency issues
• User asks to diagnose why Redis is slow or unresponsive
• User mentions queue backlog, dead letter queue, or job failures
• User wants a quick health summary of their Redis instance

When NOT to Use

❌ DON'T use this skill when:

• User wants to manage PostgreSQL, MySQL, or other non-Redis databases
• User wants to manage Kafka, RabbitMQ, or SQS queues (not BullMQ)
• User needs help writing application code that uses Redis
• User wants to set up Redis from scratch (use official Redis docs instead)

Safety Rules

⚠️ CRITICAL: This skill is READ-ONLY. No exceptions.

• NEVER run destructive commands (FLUSHDB, FLUSHALL, DEL, UNLINK, SET, EXPIRE) — even if the user asks. Explain why and suggest they run it manually instead.
• NEVER modify Redis configuration (CONFIG SET) — direct the user to do it themselves.
• NEVER print or expose the full REDIS_URL in output — it may contain passwords. Always mask credentials before displaying.
• When in doubt, show the command first and ask for confirmation

Connection

If REDIS_URL is set, use it for all commands:

bash

redis-cli -u "$REDIS_URL" <command>

If REDIS_URL is not set, default to localhost:

bash

redis-cli <command>

For password-protected instances without REDIS_URL:

bash

redis-cli -h <host> -p <port> -a <password> <command>

Always test connectivity first:

bash

redis-cli -u "${REDIS_URL:-redis://localhost:6379}" ping

Server Health

Quick Status

bash

redis-cli -u "${REDIS_URL:-redis://localhost:6379}" ping

Full Server Info

bash

redis-cli -u "${REDIS_URL:-redis://localhost:6379}" info server

Connected Clients

bash

redis-cli -u "${REDIS_URL:-redis://localhost:6379}" info clients

Uptime and Version

bash

redis-cli -u "${REDIS_URL:-redis://localhost:6379}" info server | grep -E "redis_version|uptime_in_days|uptime_in_seconds|connected_clients"

Memory Analysis

Memory Overview

bash

redis-cli -u "${REDIS_URL:-redis://localhost:6379}" info memory

Key Metrics to Check

bash

redis-cli -u "${REDIS_URL:-redis://localhost:6379}" info memory | grep -E "used_memory_human|used_memory_peak_human|used_memory_rss_human|mem_fragmentation_ratio|maxmemory_human|maxmemory_policy"

Memory Doctor (Redis 4.0+)

bash

redis-cli -u "${REDIS_URL:-redis://localhost:6379}" memory doctor

Memory Usage of a Specific Key

bash

redis-cli -u "${REDIS_URL:-redis://localhost:6379}" memory usage <key>

Find Big Keys (scan-based, safe for production)

bash

redis-cli -u "${REDIS_URL:-redis://localhost:6379}" --bigkeys

Interpreting Memory Results

• mem_fragmentation_ratio > 1.5 → High fragmentation, consider restarting Redis
• mem_fragmentation_ratio < 1.0 → Redis is swapping to disk, CRITICAL
• used_memory approaching maxmemory → Eviction will start based on maxmemory_policy
• memory doctor reports "Sam, I have no memory problems" → All good

Slow Queries & Performance

Check Slow Log

bash

redis-cli -u "${REDIS_URL:-redis://localhost:6379}" slowlog get 10

Slow Log Length

bash

redis-cli -u "${REDIS_URL:-redis://localhost:6379}" slowlog len

Current Slow Log Threshold

bash

redis-cli -u "${REDIS_URL:-redis://localhost:6379}" config get slowlog-log-slower-than

Latency Check

bash

redis-cli -u "${REDIS_URL:-redis://localhost:6379}" --latency -c 10

Latency History

bash

redis-cli -u "${REDIS_URL:-redis://localhost:6379}" --latency-history -i 1 -c 5

Keyspace Stats

bash

redis-cli -u "${REDIS_URL:-redis://localhost:6379}" info keyspace

Command Stats (most called commands)

bash

redis-cli -u "${REDIS_URL:-redis://localhost:6379}" info commandstats

Client Monitoring

List Connected Clients

bash

redis-cli -u "${REDIS_URL:-redis://localhost:6379}" client list

Client Count and Summary

bash

redis-cli -u "${REDIS_URL:-redis://localhost:6379}" info clients | grep -E "connected_clients|blocked_clients|tracking_clients"

Find Idle Clients (idle > 300 seconds)

bash

redis-cli -u "${REDIS_URL:-redis://localhost:6379}" client list | awk -F' ' '{for(i=1;i<=NF;i++) if($i ~ /^idle=/) print $0}' | grep -E 'idle=[3-9][0-9]{2,}|idle=[0-9]{4,}'

BullMQ Queue Monitoring

BullMQ uses Redis as its backend. Queues follow the key pattern bull:<queue-name>:<state>.

Discover All Queues

bash

redis-cli -u "${REDIS_URL:-redis://localhost:6379}" scan 0 match "bull:*:meta" count 100

Queue Depth (all states)

For a queue named <queue>:

bash

echo "=== Queue: <queue> ==="
echo -n "Waiting: "; redis-cli -u "${REDIS_URL:-redis://localhost:6379}" llen "bull:<queue>:wait"
echo -n "Active: "; redis-cli -u "${REDIS_URL:-redis://localhost:6379}" llen "bull:<queue>:active"
echo -n "Delayed: "; redis-cli -u "${REDIS_URL:-redis://localhost:6379}" zcard "bull:<queue>:delayed"
echo -n "Failed: "; redis-cli -u "${REDIS_URL:-redis://localhost:6379}" zcard "bull:<queue>:failed"
echo -n "Completed: "; redis-cli -u "${REDIS_URL:-redis://localhost:6379}" zcard "bull:<queue>:completed"
echo -n "Paused: "; redis-cli -u "${REDIS_URL:-redis://localhost:6379}" llen "bull:<queue>:paused"

Inspect Failed Jobs

bash

redis-cli -u "${REDIS_URL:-redis://localhost:6379}" zrange "bull:<queue>:failed" 0 9

Get Job Details

bash

redis-cli -u "${REDIS_URL:-redis://localhost:6379}" hgetall "bull:<queue>:<jobId>"

Check Job Payload and Error

bash

redis-cli -u "${REDIS_URL:-redis://localhost:6379}" hmget "bull:<queue>:<jobId>" data failedReason stacktrace attemptsMade timestamp processedOn finishedOn

Find Stale Active Jobs

Active jobs that haven't been updated recently may be stuck:

bash

redis-cli -u "${REDIS_URL:-redis://localhost:6379}" lrange "bull:<queue>:active" 0 -1

Then for each job ID, check processedOn timestamp:

bash

redis-cli -u "${REDIS_URL:-redis://localhost:6379}" hmget "bull:<queue>:<jobId>" processedOn name

If processedOn is more than 10 minutes old and job is still active, it may be stuck.

Check Queue Workers (via event streams)

bash

redis-cli -u "${REDIS_URL:-redis://localhost:6379}" xinfo groups "bull:<queue>:events" 2>/dev/null || echo "No event stream found"

BullMQ Repeat Jobs

bash

redis-cli -u "${REDIS_URL:-redis://localhost:6379}" zrange "bull:<queue>:repeat" 0 -1

Key Inspection

Find Keys by Pattern

bash

redis-cli -u "${REDIS_URL:-redis://localhost:6379}" scan 0 match "<pattern>" count 100

Key Type and TTL

bash

redis-cli -u "${REDIS_URL:-redis://localhost:6379}" type <key>
redis-cli -u "${REDIS_URL:-redis://localhost:6379}" ttl <key>

Key Encoding (memory efficiency check)

bash

redis-cli -u "${REDIS_URL:-redis://localhost:6379}" object encoding <key>
redis-cli -u "${REDIS_URL:-redis://localhost:6379}" object idletime <key>

Count Keys by Prefix (useful for auditing)

bash

redis-cli -u "${REDIS_URL:-redis://localhost:6379}" eval "local count = 0; local cursor = '0'; repeat local result = redis.call('SCAN', cursor, 'MATCH', ARGV[1], 'COUNT', 1000); cursor = result[1]; count = count + #result[2]; until cursor == '0'; return count" 0 "<prefix>*"

Diagnostics — Full Health Check

Run the health check script for a comprehensive overview:

bash

bash scripts/redis-health.sh "${REDIS_URL:-redis://localhost:6379}"

This script outputs:

• Connectivity status
• Server version and uptime
• Memory usage and fragmentation
• Connected and blocked clients
• Slow query count
• All BullMQ queue depths
• Warnings for any anomalies detected

Troubleshooting Decision Trees

Redis is slow

1. Check latency: redis-cli --latency -c 10
2. If latency > 1ms → check slow log: slowlog get 10
3. If slow log has KEYS/SMEMBERS/HGETALL on large collections → advise using SCAN variants
4. Check memory fragmentation → if > 1.5, recommend restart
5. Check connected_clients → if > 1000, investigate connection pooling
6. Check blocked_clients → if > 0, check BLPOP/BRPOP consumers

Redis OOM / high memory

1. Run info memory → check used_memory vs maxmemory
2. Run --bigkeys → find largest keys
3. Check maxmemory_policy → is eviction configured?
4. Run memory doctor → follow recommendations
5. Check for missing TTLs on keys: scan and check ttl on large keys

BullMQ jobs stuck / not processing

1. Check queue depth → are jobs piling up in wait?
2. Check active list → are jobs stuck in active state?
3. Check for stale active jobs → processedOn too old
4. Check event stream → xinfo groups to verify workers are connected
5. Check failed set → read failedReason and stacktrace
6. Check Redis connectivity → can workers reach Redis?

BullMQ high failure rate

1. Get recent failed jobs: zrange bull:<queue>:failed -10 -1
2. For each, read failedReason and stacktrace
3. Group errors by type → is it one recurring error or varied?
4. Check attemptsMade → are retries exhausted?
5. Check job data → is the payload malformed?

Notes

• All commands default to redis://localhost:6379 if REDIS_URL is not set
• The scan command is safe for production (non-blocking), unlike keys which should NEVER be used in production
• BullMQ key patterns assume default prefix bull:. If a custom prefix is used, replace bull: accordingly
• For Redis Cluster, add -c flag to redis-cli commands
• For Redis Sentinel, connect to the sentinel first to discover the master