# Cache Observability

> Track cache hit rates, latency, and detect cache-related issues

- Skill: `majiayu000/cache-observability` (Agent Skill, multi-file: 2 files)
- Install (CLI): `npx skillmds add majiayu000/cache-observability`
- Raw SKILL.md: https://api.skillmd.com/api/skills/majiayu000/cache-observability/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: majiayu000 (https://skillmd.com/u/majiayu000)
- Updated: 2026-09-09
- Page: https://skillmd.com/skills/majiayu000/cache-observability

---


# Cache Observability

Cache is performance-critical. Track hit rate, latency, and evictions.

## Key Metrics

| Metric | Type | Description |
|--------|------|-------------|
| `cache.hits` | Counter | Successful reads |
| `cache.misses` | Counter | Reads that missed |
| `cache.gets.duration` | Histogram | GET latency |
| `cache.evictions` | Counter | Keys evicted |
| `cache.memory.used` | Gauge | Memory consumption |

## Span Attributes

| Attribute | Example | Required |
|-----------|---------|----------|
| `cache.system` | redis, memcached | Yes |
| `cache.operation` | GET, SET | Yes |
| `cache.hit` | true/false | Yes |
| `cache.key_prefix` | user:* | Recommended (**not full key!**) |

## Hit Rate

```
hit_rate = cache.hits / (cache.hits + cache.misses)
```

- **Good:** >90%
- **Concerning:** <80% → Check TTL, warming strategy

## Issues to Detect

| Issue | Detection | Fix |
|-------|-----------|-----|
| **Low hit rate** | <80% | Tune TTL, warm cache |
| **Cache stampede** | Many misses for same key | Distributed locks |
| **High latency** | p99 >10ms | Check network, value size |
| **Memory pressure** | memory >90% of max | Eviction policy, sizing |

## Cache Wrapper Pattern

```
Before GET: Start timer
After GET:  Record duration, increment hits or misses, set cache.hit on span
```

## Anti-Patterns

- **Full keys in metrics** → High cardinality, use prefix only
- **No eviction monitoring** → Can't detect memory pressure
- **Ignoring serialization time** → Track total time including marshal

## References

- `references/platforms/{platform}/cache.md`