# Diagnosing low cache hit rate on Upstash Redis

## Symptom

Most requests miss the cache and fall through to the origin. The
origin is overloaded and Redis looks useless.

## Step 1: measure

Over the native protocol, INFO stats reports keyspace_hits and
keyspace_misses. Hit rate is hits divided by hits plus misses. Sample
it twice, a minute apart, during real traffic. A healthy cache is
usually above 80-90% for read-heavy workloads. Anything under 50%
deserves investigation.

Note: the read-only token blocks SCAN and KEYS, so run analysis with
the standard token, server side.

## Step 2: find the cause

- TTLs too short: keys expire before they are re-read. Check TTL on
your hottest keys.
- No TTL at all plus a write-heavy keyspace: the cache fills with
  one-shot keys and eviction or memory pressure churns the hot set.
- Key design that never repeats: user-specific or request-specific
  keys with no sharing are not a cache, they are a log.
- Cold cache after deploys: every deploy wipes in-memory state if you
  also cache locally. Warm the shared cache on boot, not on first
  user request.

## Step 3: fix

- Set TTLs from access patterns: hot data gets long TTLs, and
  refresh on read for sliding freshness where it matters.
- Namespace keys by what invalidates them (product:123 not
  page:homepage:2026-09-26) so one invalidation clears exactly the
  stale set.
- Invalidate on write: the writer deletes or rewrites the affected
  keys in the same code path that changes the source of truth.

## Verify

Re-sample hit rate after one full TTL cycle. It should climb and the
origin load should fall in proportion.