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.
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.
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), 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 aget()and aput()written by hand. Each is timed from the miss to the write, which is what a value costs to work out. Aput()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#
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.
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:
'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.
| Event | When | Severity | Sent |
|---|---|---|---|
Cache stampedecache_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 unreadcache_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 |
'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.