tracer-cloud--opensre/docs/redis.mdx

---
title: "Redis"
description: "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

```bash
opensre integrations setup
```

Select **Redis** when prompted and provide your host and port.

### Option 2: Environment variables

Add to your `.env`:

```bash
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`:

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

<Info>
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.
</Info>

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

<Info>
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).
</Info>

## Verify

```bash
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.