Redis Plugin

Monitor Redis cache and database instances with comprehensive metrics tracking memory usage, performance, persistence, and replication.

Overview

The Redis plugin collects detailed metrics from Redis servers including:

• Memory Usage - Memory consumption, fragmentation, peak usage
• Performance - Commands per second, keyspace hits/misses, cache efficiency
• Connections - Connected clients, blocked clients, rejected connections
• Persistence - RDB and AOF status, last save time, changes since last save
• Replication - Master/slave status, replication lag, connected slaves
• Keyspace - Keys per database, expiring keys, average TTL

Requirements

Redis Version

• Minimum: Redis 4.0
• Recommended: Redis 6.0 or later
• Tested with: Redis 5.0, 6.0, 6.2, 7.0, 7.2

Python Dependencies

pip install redis>=4.5.0

Auto-installed when using PLUGINS=redis during agent installation.

Network Access

The agent must be able to connect to Redis:

# Test connectivity
redis-cli -h localhost -p 6379 ping

Expected response: PONG

Configuration

Basic Configuration

plugins:
  redis:
    enabled: true
    host: localhost
    port: 6379

With Password

plugins:
  redis:
    enabled: true
    host: localhost
    port: 6379
    password: 'your-redis-password'

With SSL/TLS

plugins:
  redis:
    enabled: true
    host: redis.example.com
    port: 6380
    password: 'your-redis-password'
    ssl: true

Remote Redis Server

plugins:
  redis:
    enabled: true
    host: redis-server.example.com
    port: 6379
    password: 'secure-password'
    database: 0

All Configuration Options

plugins:
  redis:
    enabled: true           # Enable/disable plugin
    host: localhost         # Redis hostname or IP
    port: 6379             # Redis port (default: 6379)
    password: ''           # Redis password (optional)
    database: 0            # Database number to connect to (default: 0)
    ssl: false             # Use SSL/TLS connection (default: false)
    socket_timeout: 5      # Connection timeout in seconds (default: 5)
    socket_connect_timeout: 5  # Connect timeout in seconds (default: 5)

Environment Variables

Configuration can be overridden with environment variables:

export REDIS_HOST="localhost"
export REDIS_PORT="6379"
export REDIS_PASSWORD="secret"
export REDIS_DATABASE="0"
export REDIS_SSL="false"

Collected Metrics

All metrics are collected from the Redis INFO command.

Notes:

• Memory Fragmentation Ratio: Healthy range is 1.0-1.5. Values < 1.0 indicate swapping (bad), values > 1.5 indicate fragmentation (consider restart)
• Hit Rate: Calculated as keyspace_hits / (keyspace_hits + keyspace_misses) * 100. Healthy cache should have > 90% hit rate
• Connected Slaves: Only relevant for master instances in replication setup

Dashboard Metrics

The StatusRadar dashboard displays:

Overview Card

• Status - Redis server up/down
• Uptime - Human-readable uptime (converted from uptime_seconds)
• Connected Clients - Active client connections

Memory Usage Chart

• Used Memory (MB) - used_memory_mb
• Peak Memory (MB) - used_memory_peak_mb
• Memory Fragmentation Ratio - memory_fragmentation_ratio

Performance Chart

• Operations per second - ops_per_sec
• Cache hit rate (%) - hit_rate_percent
• Keyspace hits (total) - keyspace_hits_total
• Keyspace misses (total) - keyspace_misses_total

Eviction & Expiration

• Evicted keys (total) - evicted_keys
• Expired keys (total) - expired_keys

Replication Status

• Connected slaves - connected_slaves
• Last RDB save time - rdb_last_save_time

Redis Configuration

No Special Configuration Required

Redis monitoring works with default Redis configuration. No special settings needed.

Optional: Secure with Password

Set Redis password:

Edit /etc/redis/redis.conf:

requirepass your-secure-password-here

Restart Redis:

sudo systemctl restart redis

Update agent configuration:

plugins:
  redis:
    enabled: true
    password: 'your-secure-password-here'

Optional: Enable Persistence

RDB (Snapshotting):

Edit /etc/redis/redis.conf:

save 900 1      # Save after 900 sec if 1 key changed
save 300 10     # Save after 300 sec if 10 keys changed
save 60 10000   # Save after 60 sec if 10000 keys changed

AOF (Append-Only File):

appendonly yes
appendfsync everysec  # Options: always, everysec, no

Optional: Limit Memory

Prevent unlimited memory growth:

maxmemory 2gb
maxmemory-policy allkeys-lru  # LRU eviction policy

Eviction Policies:

• noeviction - Return errors when memory limit reached
• allkeys-lru - Evict least recently used keys
• volatile-lru - Evict LRU keys with expire set
• allkeys-random - Evict random keys
• volatile-random - Evict random keys with expire set
• volatile-ttl - Evict keys with shortest TTL

Installation

Quick Install

PLUGINS='redis' \
TOKEN='your-agent-token' \
bash -c "$(curl -sL https://statusradar.dev/install-agent.sh)"

Install on Existing Agent

1. Install Python dependency:

   cd /opt/statusradar
   source venv/bin/activate  # If using venv
   pip install redis

2. Enable plugin in config:

   sudo nano /opt/statusradar/config/agent.yaml

   Add:

   plugins:
     redis:
       enabled: true
       host: localhost
       port: 6379

3. Restart agent:

   sudo systemctl restart statusradar-agent

4. Verify:

   sudo journalctl -u statusradar-agent -n 50 --no-pager | grep redis

   Expected:

   INFO: Plugin redis: Metrics collected successfully

Testing

Manual Plugin Test

cd /opt/statusradar
export PLUGINS=redis
python3 plugins/redis_plugin.py

Expected Output:

Plugin name: redis
Enabled: True
Available: True

Metrics collected (13 keys):
  used_memory_mb: 32.5
  memory_fragmentation_ratio: 1.2
  keyspace_hits_total: 1000
  keyspace_misses_total: 100
  hit_rate_percent: 90.91
  connected_clients: 5
  ops_per_sec: 42
  evicted_keys: 0
  expired_keys: 50
  uptime_seconds: 86400
  used_memory_peak_mb: 48.3
  connected_slaves: 0
  rdb_last_save_time: 1697123456
}

Test Redis Connectivity

# Basic ping
redis-cli ping

# With password
redis-cli -a your-password ping

# Remote server
redis-cli -h redis.example.com -p 6379 -a password ping

# Check INFO output
redis-cli info

Troubleshooting

Plugin Not Collecting Metrics

Check 1: Is Redis running?

sudo systemctl status redis

Check 2: Can agent connect?

redis-cli -h localhost -p 6379 ping

Check 3: Is password correct?

redis-cli -a your-password ping

Check 4: Is plugin enabled?

grep -A5 "redis:" /opt/statusradar/config/agent.yaml

Check 5: Is Python package installed?

python3 -c "import redis; print(redis.__version__)"

Common Errors

"Connection refused"

Error:

ERROR: Plugin redis: [Errno 111] Connection refused

Cause: Redis not running or wrong host/port

Solution:

# Check if Redis is running
sudo systemctl status redis

# Start Redis
sudo systemctl start redis

# Verify port
sudo netstat -tlnp | grep 6379

# Check configuration
cat /opt/statusradar/config/agent.yaml | grep -A5 redis

"Authentication required"

Error:

ERROR: Plugin redis: NOAUTH Authentication required

Cause: Redis requires password but none provided

Solution:

Add password to agent configuration:

plugins:
  redis:
    enabled: true
    password: 'your-redis-password'

"No module named 'redis'"

Error:

ERROR: No module named 'redis'

Cause: Python redis package not installed

Solution:

pip install redis
# Or
cd /opt/statusradar && source venv/bin/activate && pip install redis

"Wrong password"

Error:

ERROR: Plugin redis: WRONGPASS invalid username-password pair

Cause: Incorrect password in configuration

Solution:

1. Check Redis password:

   grep "^requirepass" /etc/redis/redis.conf

2. Update agent configuration with correct password

3. Restart agent:

   sudo systemctl restart statusradar-agent

Metrics Showing Zero

Symptom: Some metrics always show 0

Check INFO output:

redis-cli info

Look for:

• keyspace_hits:0, keyspace_misses:0 - No cache activity yet
• connected_slaves:0 - Server is not a master with slaves
• db0_keys:0 - No keys in database 0

This is normal if:

• Redis just started
• No application is using it yet
• Database is empty

Performance Impact

On Redis

Negligible impact:

• Plugin executes INFO ALL command once per collection interval
• INFO command is lightweight (< 1ms execution time)
• Read-only operation, no data modification
• No lock contention

Benchmark:

• Redis QPS with monitoring: 100,000+ ops/sec
• Redis QPS without monitoring: 100,000+ ops/sec
• Overhead: < 0.01%

On Agent

Resource usage:

• Memory: +10 MB
• CPU: +2% during collection (0.1-0.3 seconds)
• Network: +1 KB per collection

Use Cases

1. Cache Performance Monitoring

Monitor:

• Hit rate (should be > 90%)
• Evicted keys (high eviction = need more memory)
• Memory fragmentation

Alert on:

• Hit rate < 80%
• Memory usage > 90%
• Fragmentation ratio > 1.5

2. Session Store Monitoring

Monitor:

• Connected clients
• Total keys
• Expiring keys

Alert on:

• Sudden client drop (application crash)
• Keys not expiring (memory leak)

3. Queue Monitoring

Monitor:

• Blocked clients (queue consumers)
• List lengths (via custom scripts)
• Operations per second

Alert on:

• No blocked clients (consumers died)
• High ops/sec (queue flooding)

4. Replication Monitoring

Monitor:

• Slave connection status
• Replication lag
• Connected slaves count

Alert on:

• Slave disconnected
• Replication lag > 10 seconds
• Slave count dropped

Best Practices

1. Use Latest Redis Version

Benefits:

• Better memory efficiency
• Improved INFO command performance
• More detailed metrics

2. Enable Persistence for Production

RDB for backups:

save 900 1
save 300 10
save 60 10000

AOF for durability:

appendonly yes
appendfsync everysec

3. Set Maxmemory Limit

Prevent OOM:

maxmemory 4gb
maxmemory-policy allkeys-lru

4. Monitor Memory Fragmentation

If mem_fragmentation_ratio > 1.5:

• Restart Redis during low-traffic window
• Consider using jemalloc allocator

5. Secure with Password

Always set requirepass in production:

requirepass strong-random-password-here

6. Monitor Replication Lag

For master-slave setups, set alert for:

• master_link_status = 0 (slave disconnected)
• lag > 5 seconds

Advanced Configuration

Multiple Redis Instances

To monitor multiple Redis instances, deploy separate agents or use Sentinel/Cluster monitoring (coming soon).

Redis Cluster

Plugin monitors individual nodes. For cluster-wide metrics, query each node separately.

Redis Sentinel

Plugin connects to Redis instance, not Sentinel. Monitor Sentinel separately via HTTP API.

Example Configurations

Development Server

plugins:
  redis:
    enabled: true
    host: localhost
    port: 6379

Production Server (Secured)

plugins:
  redis:
    enabled: true
    host: localhost
    port: 6379
    password: 'strong-password-from-env'
    database: 0

Remote Redis (SSL)

plugins:
  redis:
    enabled: true
    host: redis.example.com
    port: 6380
    password: 'secure-password'
    ssl: true
    socket_timeout: 10

Redis on Custom Port

plugins:
  redis:
    enabled: true
    host: localhost
    port: 6380  # Custom port
    password: 'password'

Metric Reference

Full Metric List

The plugin collects 13 metrics from Redis INFO command:

Memory (3 metrics):

• used_memory_mb - Current memory usage in megabytes
• used_memory_peak_mb - Peak memory usage in megabytes
• memory_fragmentation_ratio - Memory fragmentation ratio

Performance (5 metrics):

• ops_per_sec - Current operations per second
• keyspace_hits_total - Total successful key lookups (counter)
• keyspace_misses_total - Total failed key lookups (counter)
• hit_rate_percent - Calculated cache hit rate percentage
• connected_clients - Number of connected clients

Eviction & Expiration (2 metrics):

• evicted_keys - Total keys evicted due to maxmemory (counter)
• expired_keys - Total keys expired (counter)

System (2 metrics):

• uptime_seconds - Redis server uptime in seconds

Replication (1 metric):

• connected_slaves - Number of connected replica instances

Persistence (1 metric):

• rdb_last_save_time - Unix timestamp of last RDB snapshot

Next Steps

• View all plugins
• MySQL Plugin
• PostgreSQL Plugin
• Nginx Plugin
• Agent Configuration Guide