ElastiCache Hot Shard Debugger

Debug hot shard issues in AWS ElastiCache (Redis/Valkey) clusters with a beautiful web interface.

Quick Start

# Install
pip install elasticache-monitor

# Run
elasticache-monitor

Open http://localhost:8099 and start monitoring!

---

Features

• 🌐 Web Interface — Modern UI with real-time updates
• ⏱️ Live Monitoring — Countdown timer, per-shard status
• 📊 Interactive Charts — Click to filter, right-click to hide
• 🔍 Analysis — Sortable tables for keys, patterns, shards, commands
• 🔄 Compare Jobs — Side-by-side comparison of 2-4 sessions
• 💾 SQL Queries — Built-in editor with quick query templates

---

Usage

1. Start the Server

elasticache-monitor              # Default port 8099
elasticache-monitor --port 3000  # Custom port

2. Create a Monitoring Job

1. Enter your Replication Group ID
2. Enter your Redis/Valkey password
3. Set duration (30-300 seconds)
4. Click Start Monitoring

3. View Results

• Dashboard — Real-time command counts, shard status
• Charts — Command distribution, key patterns
• Analysis — Deep dive into keys and patterns
• Compare — Compare multiple monitoring sessions

---

Requirements

• Python 3.12+
• AWS credentials (for endpoint auto-discovery)
• Network access to ElastiCache cluster

Install

# Using uv (recommended)
uv pip install -e .

# Or pip
pip install -e .

---

Production Safety

⚠️ Always use replica endpoints for monitoring in production. The MONITOR command can impact performance on primary nodes.

The web UI defaults to replica endpoints.

---

AWS Permissions

{
  "Effect": "Allow",
  "Action": [
    "elasticache:DescribeReplicationGroups",
    "elasticache:DescribeCacheClusters"
  ],
  "Resource": "*"
}

---

Documentation

Document	Description
CLI Reference	Command-line tools (for scripting)
Database Schema	SQLite schema & example queries
Changelog	Version history

---

CLI (Legacy)

For scripting and automation, CLI tools are still available:

elasticache-monitor-cli -c my-cluster -p PASSWORD -d 60

See docs/CLI.md for full reference.

---

Version: 2.0.0 · Python: 3.12+ · License: MIT