# The Cache page

> What the application does with its cache, for each group of keys: hits and misses, how long a value took to generate, entries generated twice at once and entries never read.

Source: https://boring-observability.dev/sailfish/docs/cache
Section: Redis and the cache — Sailfish documentation (version 0.4)
Updated: 2026-11-17

---

A hit ratio tells you how often the cache answered, and nothing about what a miss cost or whether what you cached was ever wanted. With `SAILFISH_CACHE_ENABLED` set, Sailfish listens to the application's cache events, on every store whatever its driver, and counts what each group of keys costs: how long a value took to work out after a miss, how big it was, how often two processes worked out the same one, and how many entries ended without anyone reading them.

```bash
SAILFISH_CACHE_ENABLED=true
SAILFISH_CACHE_REDIS_CONNECTION=default   # or leave it out to use SAILFISH_REDIS_CONNECTION
```

The counts are buffered in Redis until a collection takes them (see [what it costs](#cost)), so a Redis connection is needed even when the cache itself is on the file, database or Memcached store. With neither variable set, nothing is recorded and the Cache page says how to turn it on.

## What is counted

For each group of keys, over every interval:

- **Hits and misses**, and so the hit ratio.
- **Generations.** A miss followed by a write of the same key, in the same store and under the same tags, in the same process: `Cache::remember()`, `Cache::flexible()`, or a `get()` and a `put()` written by hand. Each is timed from the miss to the write, which is what a value costs to work out. A `put()` with no miss before it is a write, not a generation. `Cache::flexible()`'s refresh in the background counts as a generation too, and is counted apart.
- **Size:** what each write holds, as PHP serializes it, or a number's digits. A store that compresses, or serializes with igbinary, holds less.
- **Generated twice at once:** a generation that began while another process was already generating the same key, before its write landed. Under load, a popular key that expires is missed by every request until one of them writes it back, and each of them works it out.
- **Never read:** each entry is followed from its write until it expires, is forgotten or is written over, and counted as never read if nothing read it in between. A group whose entries mostly end unread caches what nobody asks for again within its TTL.

Sailfish never stores a key itself, only its group, and never a value.

## The Cache page

![The Sailfish Cache page for a demo shop over seven days: a 97% hit ratio over 74.8 million lookups, 99.6 hours spent generating at 158 ms a generation, 67,801 generations begun while another process was generating the same key, 55% of ended entries never read and 43.9 MiB held now; charts of lookups, time spent generating and generations; and the groups table, led by product_recommendations at 68.5 hours spent generating.](https://boring-observability.dev/shots/sailfish/cache.png)

*A week of a demo shop's cache. product_recommendations takes the most time to generate, and is often generated twice at once.*

Across the top: the hit ratio, the time spent generating values and how long one took on average, generations that ran twice at once, the share of entries that ended unread, and what the cache holds now. Below are charts of lookups, time spent generating and generations, with those that ran twice at once drawn beside them.

The table lists every group with its lookups, hit ratio, generations, the mean and longest generation, the time spent generating in all, generations twice at once, the share never read, the size of an entry and what the group holds now. It is sorted by time spent generating, so what costs the most comes first, and every column sorts. A group that is cheap to generate and rarely hit may not be worth caching at all.

Each group has a page charting its lookups, its generations, the time a generation took and the entries that ended, with those never read, and listing its events.

![The Sailfish page for the product_recommendations cache group over seven days: a 98% hit ratio at 21 lookups a second; 293,499 generations at 840 ms each on average and up to 3.9 s, 68.5 hours in all; 58,593 of them, 20%, begun while another process was generating the same key; and charts of lookups and of generations, with those begun twice at once rising and falling with the day's load.](https://boring-observability.dev/shots/sailfish/cache-group.png)

*product_recommendations over the same week. A fifth of its generations began while another process was already working out the same key, more of them in the afternoon, when the shop is busiest.*

## How keys are grouped

A key's group is its first segment, split on `:`, with whatever looks like an identifier folded to `*`: a number standing on its own, a UUID, a hexadecimal hash of 16 characters or more, and any run of 32 letters and digits with a digit in it, such as a session id.

| Key | Group |
| --- | --- |
| `product_recommendations:4411` | `product_recommendations` |
| `user_123_permissions` | `user_*_permissions` |
| `category_tree` | `category_tree` |
| `lw_computed.UIN5SMDZdE4DDtLTE26Z.reviewsData` | `lw_computed.*.reviewsData` |

The last is a Livewire `#[Computed(persist: true)]` property: its component id is folded, so every component with a `reviewsData` property shares one group rather than getting one each.

`SAILFISH_CACHE_KEY_DEPTH=2` keeps two segments, so `shipping_quote:dhl:4411` is `shipping_quote:dhl`. The store's own prefix is not part of the key: a Redis key `app_cache:shipping_quote:dhl:4411` is `shipping_quote:dhl:4411` to the cache. Each store has its own groups, and the same key under other tags is another entry in the same group.

`cache.groups` names groups of your own by `Str::is()` pattern, the first match winning. A pattern on its own is its group's name:

```php
'cache' => [
    'groups' => [
        'shipping_quote:dhl:*' => 'DHL quotes',
        'admin.sidebar.*',
    ],
    'ignore' => [
        'illuminate:*',
        'framework/schedule-*',
    ],
    'max_groups' => 1_000,
],
```

Keys matching `cache.ignore` are not counted. By default that is Laravel's own: the queue's restart signal that every worker reads on every loop, the locks and timestamps of `Cache::flexible()`, and the scheduler's overlap checks. Past `max_groups`, new groups are counted together as `(other)`, so a key pattern nothing folds cannot fill the table. Groups unused for `retention.cache_key_days` (90) that hold no entries are pruned by the rollup, which makes room again.

## What it costs

Each request, job or command that used the cache keeps what it saw in memory and leaves it in Redis as it ends, in one script call: its counts by group, and the entries it wrote, read and forgot. A queue worker does so after each job, Octane after each request, and anything else that runs long every 1,000 operations or 30 seconds. Sailfish's keys in that Redis start with `sailfish:{cache}:`, after the connection's prefix.

Following entries costs about 100 bytes of Redis for each, up to `cache.max_entries` (100,000) at once. Past that, new entries are counted as written but not followed, and the Cache page says how many, since whether they were read is not known. Every collection takes the counts, ends the entries whose TTL has passed and keeps a sample for each group that was used. As for MySQL, the first collection is a baseline.

A Redis that cannot be reached fails nothing: the application carries on, and what that process saw is lost. `sailfish:collect` warns when it cannot take the counts, and collects the rest.

## What it cannot see

Sailfish sees what the application does, not what the store does. An entry that Redis evicts, or that a tag's flush empties, is followed until its TTL ends, and counted as never read if it was not. One cached forever is let go, uncounted, once nothing has read or written it for `cache.idle_hours` (24), so entries the store dropped without a word cannot fill `max_entries` for good.

`Cache::clear()` and `php artisan cache:clear` end every entry of their store at once, counted neither as expired nor as written over. `Cache::flush()` raises no event the application can hear, so its entries are followed as an eviction's are. `Cache::memo()` counts what reaches the store beneath it.

## Events

What a stampede looks like under load, and how a lock or `Cache::flexible()` stops one, is in [Cache stampedes in Laravel](https://boring-observability.dev/blog/laravel-cache-stampede).

| Event | When | Severity | Sent |
| --- | --- | --- | --- |
| **Cache stampede** `cache_stampede` | A group's keys were generated in two processes at once at least 10 times over the last hour, each generation taking at least 50 ms on average: whichever finished second did the work for nothing. It says how much time that wasted and suggests Cache::flexible(), or for a group already using it, that its keys were missed outright. | warning | Daily digest |
| **Cache entries unread** `cache_unread` | At least half of a group's entries that expired or were forgotten or written over in the last 24 hours were never read, of at least 100. It says what generating them cost and how big they were. | info | Daily digest |

```php
'cache_stampede' => [
    'enabled' => true,
    'min_per_hour' => 10,          // generations twice at once in the last hour
    'min_generation_ms' => 50,     // each taking this long on average
],
'cache_unread' => [
    'enabled' => true,
    'hours' => 24,
    'min_share' => 0.5,            // of the entries that ended
    'min_entries' => 100,
],
```

A stampede says how much time the second generations wasted, and suggests `Cache::flexible()`, which serves the stale value while one process refreshes it. For a group already using it, it says its keys were missed outright, as happens when they expired past the stale window. Both events go in the daily digest: they are a change to make in the code, not an outage.


## Common questions

### Does the cache have to be on Redis?

No. Sailfish listens to the application's cache events, so any store counts: file, database, Memcached, DynamoDB or Redis. The counts are buffered in Redis until a collection takes them, so it needs a Redis connection for that, named by SAILFISH_CACHE_REDIS_CONNECTION or SAILFISH_REDIS_CONNECTION.

### What is a cache stampede?

A popular key expires under load, and every request that misses it works the value out until one of them writes it back. Sailfish counts each generation that began while another process was already generating the same key, and opens a cache stampede event when a group does that at least 10 times in an hour with generations of 50 ms or more. Cache::flexible() serves the stale value meanwhile and refreshes it once.

### Does recording the cache slow the application down?

Each request, job or command keeps its counts in memory and hands them to Redis in one script call as it ends; a queue worker does so after each job. Following entries from write to expiry costs about 100 bytes of Redis each, up to 100,000 at once. A Redis that cannot be reached fails nothing.
