Redis

Connect Redis so OpenSRE can diagnose cache, queue, and session issues during investigations

OpenSRE uses Redis diagnostics to investigate cache and key-value store alerts — checking memory pressure and eviction rates, surfacing slow commands, monitoring replication lag, and inspecting key counts and TTLs. Redis is one of the most common components in SRE stacks (caching, queues, session storage, rate limiting), and these tools give an investigation visibility into all of them.

Prerequisites

• Redis 5.0+ (or a compatible server such as Valkey)
• Network access from the OpenSRE environment to your Redis instance
• Credentials, if authentication (requirepass or ACLs) is enabled

Setup

Option 1: Interactive CLI

opensre integrations setup

Select Redis when prompted and provide your host and port.

Option 2: Environment variables

Add to your .env:

REDIS_HOST=localhost
REDIS_PORT=6379
REDIS_USERNAME=
REDIS_PASSWORD=
REDIS_DATABASE=0
REDIS_SSL=false

Variable	Default	Description
REDIS_HOST	—	Required. Redis hostname or IP
REDIS_PORT	6379	Redis port
REDIS_USERNAME	(empty)	ACL username (Redis 6+); leave blank for password-only auth
REDIS_PASSWORD	(empty)	Password (requirepass or ACL)
REDIS_DATABASE	0	Database number to inspect
REDIS_SSL	false	Connect using TLS

Option 3: Persistent store

Integrations are automatically persisted to ~/.opensre/integrations.json:

{
  "version": 1,
  "integrations": [
    {
      "id": "redis-prod",
      "service": "redis",
      "status": "active",
      "credentials": {
        "host": "cache.example.net",
        "port": 6379,
        "username": "",
        "password": "s3cret",
        "db": 0,
        "ssl": true
      }
    }
  ]
}

Authentication

• Password only (requirepass): set REDIS_PASSWORD and leave REDIS_USERNAME blank.
• ACL user (Redis 6+): set both REDIS_USERNAME and REDIS_PASSWORD.
• No auth: leave both blank (development only).

TLS configuration

Set REDIS_SSL=true to connect over TLS. Confirm the server has TLS enabled (e.g. tls-port 6379).

Investigation tools

When OpenSRE investigates a Redis-related alert, seven read-only diagnostic tools are available:

Server info

Retrieves version, uptime, memory usage (used, RSS, peak, maxmemory, fragmentation ratio, eviction policy), connected/blocked clients, throughput and hit/miss counters, eviction and expiry counts, and per-database keyspace statistics. Useful for spotting memory pressure, high eviction rates, or connection saturation.

Slow log

Returns recent SLOWLOG entries — the command, execution duration (microseconds), and originating client. Surfaces expensive commands such as large KEYS, SMEMBERS, or SORT operations.

Replication

Reports the node role, master link health (for replicas), connected replicas, and per-replica offset lag in bytes (for masters). Identifies broken replication or replicas falling behind.

Key scan

Counts keys matching a glob pattern and samples their TTL and type.

Key discovery uses the non-blocking SCAN cursor — never KEYS — so it is safe to run against large production keyspaces. Total iteration is capped (10,000 keys) and TTL/type sampling is bounded, so a wide pattern can never run unbounded.

Client list

Summarizes connected clients via CLIENT LIST: total connections, how many are blocked (waiting on BLPOP/BRPOP/XREAD), how many are in pub/sub mode, the longest idle time, and breakdowns by source address and last command. Surfaces connection-pool exhaustion and stuck or blocked clients. Aggregate counts cover every client; the per-client sample is bounded.

List/queue depth

Reports a list key’s depth via LLEN, with an optional bounded head/tail sample via LRANGE. Useful for job-queue backlogs and stuck workers (Sidekiq, Celery, Bull, Resque-style queues). The key’s TYPE is checked first, so a missing key reports exists: false and a non-list key returns a clear message rather than a WRONGTYPE error. Each sampled element is length-capped.

Latency doctor

Runs LATENCY DOCTOR for a human-readable diagnosis of recent latency spikes (fork/RDB save, AOF rewrite, blocking commands, slow disk) and lists the latest monitored events via LATENCY LATEST; an optional event argument adds LATENCY HISTORY for that event.

Latency monitoring must be enabled for events to be recorded — set latency-monitor-threshold to a value greater than 0 (in milliseconds). The tool reads this threshold via CONFIG GET, so monitoring_active reflects whether monitoring is enabled (a healthy, enabled-but-quiet server reports monitoring_active: true with no events). When the threshold is 0, monitoring_active is false and monitoring_threshold_ms is 0; the report field still carries Redis’s raw LATENCY DOCTOR output (Redis itself does not emit a special “disabled” message).

Verify

opensre integrations verify redis

Expected output:

Service: redis
Status: passed
Detail: Connected to Redis 7.2.4 at localhost:6379; database 0.

Troubleshooting

Symptom	Fix
Connection refused	Verify the host/port, check firewalls, and ensure Redis is running and bound to a reachable interface (protected-mode).
Authentication failed (NOAUTH/WRONGPASS)	Set REDIS_PASSWORD. For ACL users, also set REDIS_USERNAME.
No permissions (NOPERM)	Grant the user read access to the diagnostic commands it needs: INFO, CLIENT, SLOWLOG, LATENCY, TYPE, LLEN/LRANGE, SCAN/TTL (and CONFIG GET for the latency-monitoring threshold).
TLS handshake failed	Set REDIS_SSL=true; confirm the server has TLS enabled.
Empty replication / no replicas	Expected for a standalone instance — the role is reported as master with no replicas.

Security best practices

• Use a read-only Redis ACL user for monitoring — the tools never write.
• Always enable TLS (REDIS_SSL=true) for connections over untrusted networks.
• Store the host and password in .env, never in code.
• Rotate credentials periodically.