CacheStats
in package
Observability counters of the wire-payload query cache.
Counters are HINCRBY increments in Redis hashes:
{prefix}cache:stats:{ServiceFQCN}with fields hit, miss_cold, miss_invalidated, set,{prefix}cache:stats:_totalwith the same fields aggregated plus bump (no service dimension).
The counters add at most one pipelined command to the hot path: the per-service and _total
increments share one Predis pipeline (one round-trip). A bump has no service context (it runs
in CacheTagInvalidator after the commit), so it goes to _total only.
IMPORTANT: everything is fail-open and fire-and-forget; an exception from a counter never propagates, otherwise a counter could break the request or data that is already saved. Gated by Config::$statsEnabled.
Table of Contents
Constants
- FIELD_BUMP : mixed = 'bump'
- Tag invalidation (`INCR` in `CacheTagInvalidator`).
- FIELD_HIT : mixed = 'hit'
- Cache hit (valid payload).
- FIELD_MISS_COLD : mixed = 'miss_cold'
- Miss: the key is missing, expired or unusable (cold rebuild).
- FIELD_MISS_INVALIDATED : mixed = 'miss_invalidated'
- Miss: the payload was cached but is invalid (tag bump or format bump).
- FIELD_SET : mixed = 'set'
- Payload write after a database read (`SETEX`).
- TOTAL : mixed = '_total'
- Field name and hash suffix of the global aggregate.
Properties
Methods
- __construct() : mixed
-
aggregate()
: array{total: array
- Aggregates all stats hashes and adds the hit rate in percent (for reports and {@see QueryCache::getStats()}). Fail-open: a Redis error returns an empty structure.
- record() : void
- Records increments for one service (per-service hash plus `_total`) in one pipeline.
- recordBump() : void
- Records a bump (tag invalidation) in the global `_total` hash with one `HINCRBY`.
- readHash() : array<string, int>
- statsKey() : string
- withHitRate() : array<string, int|float>
- Adds `hitRate`, the percentage of hits among read attempts: hit / (hit + miss_cold + miss_invalidated).
Constants
FIELD_BUMP
Tag invalidation (`INCR` in `CacheTagInvalidator`).
public
mixed
FIELD_BUMP
= 'bump'
FIELD_HIT
Cache hit (valid payload).
public
mixed
FIELD_HIT
= 'hit'
FIELD_MISS_COLD
Miss: the key is missing, expired or unusable (cold rebuild).
public
mixed
FIELD_MISS_COLD
= 'miss_cold'
FIELD_MISS_INVALIDATED
Miss: the payload was cached but is invalid (tag bump or format bump).
public
mixed
FIELD_MISS_INVALIDATED
= 'miss_invalidated'
FIELD_SET
Payload write after a database read (`SETEX`).
public
mixed
FIELD_SET
= 'set'
TOTAL
Field name and hash suffix of the global aggregate.
private
mixed
TOTAL
= '_total'
Properties
$config read-only
private
Config
$config
$redis read-only
private
Client
$redis
Methods
__construct()
public
__construct(Client $redis, Config $config) : mixed
Parameters
- $redis : Client
- $config : Config
aggregate()
Aggregates all stats hashes and adds the hit rate in percent (for reports and {@see QueryCache::getStats()}). Fail-open: a Redis error returns an empty structure.
public
aggregate() : array{total: array, services: array>}
Return values
array{total: arrayrecord()
Records increments for one service (per-service hash plus `_total`) in one pipeline.
public
record(string $serviceClass, array<string, int> $increments) : void
Fire-and-forget: any error is swallowed.
Parameters
- $serviceClass : string
- $increments : array<string, int>
-
field to count (e.g.
[FIELD_HIT => 1])
recordBump()
Records a bump (tag invalidation) in the global `_total` hash with one `HINCRBY`.
public
recordBump([int $count = 1 ]) : void
Fire-and-forget.
Parameters
- $count : int = 1
readHash()
private
readHash(string $key) : array<string, int>
Parameters
- $key : string
Return values
array<string, int>statsKey()
private
statsKey(string $name) : string
Parameters
- $name : string
Return values
stringwithHitRate()
Adds `hitRate`, the percentage of hits among read attempts: hit / (hit + miss_cold + miss_invalidated).
private
withHitRate(array<string, int> $fields) : array<string, int|float>
Parameters
- $fields : array<string, int>