From 6e84e3c8a50fd1fa8c3ff814b23a2c041cdc9a1e Mon Sep 17 00:00:00 2001 From: loks0n <22452787+loks0n@users.noreply.github.com> Date: Tue, 19 May 2026 15:14:37 +0100 Subject: [PATCH 1/4] feat: emit cache.load.total counter with hit/miss result Adds a separate counter for load outcomes so hitrate can be computed without exploding histogram cardinality across le buckets. Co-Authored-By: Claude Opus 4.7 --- src/Cache/Cache.php | 18 ++++- tests/Cache/Unit/LoadResultsTelemetryTest.php | 66 +++++++++++++++++++ 2 files changed, 83 insertions(+), 1 deletion(-) create mode 100644 tests/Cache/Unit/LoadResultsTelemetryTest.php diff --git a/src/Cache/Cache.php b/src/Cache/Cache.php index 5a9d4c5695..e404719524 100644 --- a/src/Cache/Cache.php +++ b/src/Cache/Cache.php @@ -4,6 +4,7 @@ namespace Utopia\Cache; use Utopia\Telemetry\Adapter as Telemetry; use Utopia\Telemetry\Adapter\None as NoTelemetry; +use Utopia\Telemetry\Counter; use Utopia\Telemetry\Histogram; class Cache @@ -20,6 +21,11 @@ class Cache */ protected ?Histogram $operationDuration = null; + /** + * @var Counter|null + */ + protected ?Counter $loadResults = null; + /** * Set telemetry adapter and create histograms for cache operations. * @@ -33,6 +39,11 @@ class Cache null, ['ExplicitBucketBoundaries' => [0.001, 0.005, 0.01, 0.025, 0.05, 0.1, 0.25, 0.5, 1]] ); + $this->loadResults = $telemetry->createCounter( + 'cache.load.total', + null, + 'Cache load operations broken down by hit/miss result.', + ); if ($this->adapter instanceof Feature\Telemetry) { $this->adapter->setTelemetry($telemetry); @@ -77,9 +88,14 @@ class Cache $start = microtime(true); $result = $this->adapter->load($key, $ttl, $hash); $duration = microtime(true) - $start; + $adapterName = $this->adapter->getName($key); $this->operationDuration?->record($duration, [ 'operation' => 'load', - 'adapter' => $this->adapter->getName($key), + 'adapter' => $adapterName, + ]); + $this->loadResults?->add(1, [ + 'adapter' => $adapterName, + 'result' => $result ? 'hit' : 'miss', ]); return $result; diff --git a/tests/Cache/Unit/LoadResultsTelemetryTest.php b/tests/Cache/Unit/LoadResultsTelemetryTest.php new file mode 100644 index 0000000000..3921565a3c --- /dev/null +++ b/tests/Cache/Unit/LoadResultsTelemetryTest.php @@ -0,0 +1,66 @@ +setTelemetry($telemetry); + + $cache->load('missing', 60); + $cache->save('present', 'value'); + $cache->load('present', 60); + $cache->load('present', 60); + + $this->assertArrayHasKey('cache.load.total', $telemetry->counters); + $this->assertCount(3, $telemetry->counters['cache.load.total']->values); + } + + public function testHitMissAttributesAreRecorded(): void + { + $captured = []; + + $cache = new Cache(new Memory()); + $telemetry = new class ($captured) extends TestTelemetry { + /** + * @param array> $captured + */ + public function __construct(public array &$captured) {} + + public function createCounter(string $name, ?string $unit = null, ?string $description = null, array $advisory = []): \Utopia\Telemetry\Counter + { + if ($name !== 'cache.load.total') { + return parent::createCounter($name, $unit, $description, $advisory); + } + $captured = &$this->captured; + return $this->counters[$name] = new class ($captured) extends \Utopia\Telemetry\Counter { + /** + * @param array> $captured + */ + public function __construct(public array &$captured) {} + + public function add(float|int $amount, iterable $attributes = []): void + { + $this->captured[] = \is_array($attributes) ? $attributes : \iterator_to_array($attributes); + } + }; + } + }; + $cache->setTelemetry($telemetry); + + $cache->load('absent', 60); + $cache->save('here', 'value'); + $cache->load('here', 60); + + $results = \array_column($captured, 'result'); + $this->assertSame(['miss', 'hit'], $results); + } +} From 393210b49f26dc5486506c54fab008495334eb71 Mon Sep 17 00:00:00 2001 From: loks0n <22452787+loks0n@users.noreply.github.com> Date: Tue, 19 May 2026 15:16:25 +0100 Subject: [PATCH 2/4] fix: treat only false as cache miss, not all falsy values Strict === false check so cached null/0/''/[] count as hits. Adapters use false as the miss sentinel; falsy data is still data. Co-Authored-By: Claude Opus 4.7 --- src/Cache/Cache.php | 2 +- tests/Cache/Unit/LoadResultsTelemetryTest.php | 44 +++++++++++++++++++ 2 files changed, 45 insertions(+), 1 deletion(-) diff --git a/src/Cache/Cache.php b/src/Cache/Cache.php index e404719524..89c0e039d9 100644 --- a/src/Cache/Cache.php +++ b/src/Cache/Cache.php @@ -95,7 +95,7 @@ class Cache ]); $this->loadResults?->add(1, [ 'adapter' => $adapterName, - 'result' => $result ? 'hit' : 'miss', + 'result' => $result === false ? 'miss' : 'hit', ]); return $result; diff --git a/tests/Cache/Unit/LoadResultsTelemetryTest.php b/tests/Cache/Unit/LoadResultsTelemetryTest.php index 3921565a3c..2b89bfe3b5 100644 --- a/tests/Cache/Unit/LoadResultsTelemetryTest.php +++ b/tests/Cache/Unit/LoadResultsTelemetryTest.php @@ -63,4 +63,48 @@ class LoadResultsTelemetryTest extends TestCase $results = \array_column($captured, 'result'); $this->assertSame(['miss', 'hit'], $results); } + + public function testNullReturnIsTreatedAsHit(): void + { + $captured = []; + + $adapter = new class extends Memory { + public function load(string $key, int $ttl, string $hash = ''): mixed + { + return null; + } + }; + + $cache = new Cache($adapter); + $telemetry = new class ($captured) extends TestTelemetry { + /** + * @param array> $captured + */ + public function __construct(public array &$captured) {} + + public function createCounter(string $name, ?string $unit = null, ?string $description = null, array $advisory = []): \Utopia\Telemetry\Counter + { + if ($name !== 'cache.load.total') { + return parent::createCounter($name, $unit, $description, $advisory); + } + $captured = &$this->captured; + return $this->counters[$name] = new class ($captured) extends \Utopia\Telemetry\Counter { + /** + * @param array> $captured + */ + public function __construct(public array &$captured) {} + + public function add(float|int $amount, iterable $attributes = []): void + { + $this->captured[] = \is_array($attributes) ? $attributes : \iterator_to_array($attributes); + } + }; + } + }; + $cache->setTelemetry($telemetry); + + $cache->load('any', 60); + + $this->assertSame('hit', $captured[0]['result']); + } } From ccbb5477e3d2ce8de797ee056eb565988e77a602 Mon Sep 17 00:00:00 2001 From: loks0n <22452787+loks0n@users.noreply.github.com> Date: Tue, 19 May 2026 15:18:22 +0100 Subject: [PATCH 3/4] style: apply pint formatting and phpstan ignore for Test counter Co-Authored-By: Claude Opus 4.7 --- tests/Cache/Unit/LoadResultsTelemetryTest.php | 34 ++++++++++++++----- 1 file changed, 25 insertions(+), 9 deletions(-) diff --git a/tests/Cache/Unit/LoadResultsTelemetryTest.php b/tests/Cache/Unit/LoadResultsTelemetryTest.php index 2b89bfe3b5..42995e088c 100644 --- a/tests/Cache/Unit/LoadResultsTelemetryTest.php +++ b/tests/Cache/Unit/LoadResultsTelemetryTest.php @@ -21,6 +21,7 @@ class LoadResultsTelemetryTest extends TestCase $cache->load('present', 60); $this->assertArrayHasKey('cache.load.total', $telemetry->counters); + /** @phpstan-ignore-next-line property.notFound */ $this->assertCount(3, $telemetry->counters['cache.load.total']->values); } @@ -29,11 +30,14 @@ class LoadResultsTelemetryTest extends TestCase $captured = []; $cache = new Cache(new Memory()); - $telemetry = new class ($captured) extends TestTelemetry { + $telemetry = new class($captured) extends TestTelemetry + { /** * @param array> $captured */ - public function __construct(public array &$captured) {} + public function __construct(public array &$captured) + { + } public function createCounter(string $name, ?string $unit = null, ?string $description = null, array $advisory = []): \Utopia\Telemetry\Counter { @@ -41,11 +45,15 @@ class LoadResultsTelemetryTest extends TestCase return parent::createCounter($name, $unit, $description, $advisory); } $captured = &$this->captured; - return $this->counters[$name] = new class ($captured) extends \Utopia\Telemetry\Counter { + + return $this->counters[$name] = new class($captured) extends \Utopia\Telemetry\Counter + { /** * @param array> $captured */ - public function __construct(public array &$captured) {} + public function __construct(public array &$captured) + { + } public function add(float|int $amount, iterable $attributes = []): void { @@ -68,7 +76,8 @@ class LoadResultsTelemetryTest extends TestCase { $captured = []; - $adapter = new class extends Memory { + $adapter = new class extends Memory + { public function load(string $key, int $ttl, string $hash = ''): mixed { return null; @@ -76,11 +85,14 @@ class LoadResultsTelemetryTest extends TestCase }; $cache = new Cache($adapter); - $telemetry = new class ($captured) extends TestTelemetry { + $telemetry = new class($captured) extends TestTelemetry + { /** * @param array> $captured */ - public function __construct(public array &$captured) {} + public function __construct(public array &$captured) + { + } public function createCounter(string $name, ?string $unit = null, ?string $description = null, array $advisory = []): \Utopia\Telemetry\Counter { @@ -88,11 +100,15 @@ class LoadResultsTelemetryTest extends TestCase return parent::createCounter($name, $unit, $description, $advisory); } $captured = &$this->captured; - return $this->counters[$name] = new class ($captured) extends \Utopia\Telemetry\Counter { + + return $this->counters[$name] = new class($captured) extends \Utopia\Telemetry\Counter + { /** * @param array> $captured */ - public function __construct(public array &$captured) {} + public function __construct(public array &$captured) + { + } public function add(float|int $amount, iterable $attributes = []): void { From 8366a1973925875935687e94acf89ad6b653102c Mon Sep 17 00:00:00 2001 From: loks0n <22452787+loks0n@users.noreply.github.com> Date: Tue, 19 May 2026 15:28:44 +0100 Subject: [PATCH 4/4] fix: track multiplexing pending depth as up/down counter MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit The gauge was sampled only after enqueue, so its minimum reading was always 1 and it never decreased on dequeue — drained queues kept reporting their last enqueue-time depth. Switch to an UpDownCounter so +1 on enqueue and -1 on each dequeue (reader path and teardown) yield the true real-time depth without periodic sampling. Co-Authored-By: Claude Opus 4.7 --- src/Cache/Adapter/Redis/Multiplexing.php | 18 ++++++++++-------- 1 file changed, 10 insertions(+), 8 deletions(-) diff --git a/src/Cache/Adapter/Redis/Multiplexing.php b/src/Cache/Adapter/Redis/Multiplexing.php index 388580704e..2fe5f3ce98 100644 --- a/src/Cache/Adapter/Redis/Multiplexing.php +++ b/src/Cache/Adapter/Redis/Multiplexing.php @@ -11,7 +11,7 @@ use Utopia\Cache\Adapter; use Utopia\Cache\Feature\Telemetry as TelemetryFeature; use Utopia\Telemetry\Adapter as Telemetry; use Utopia\Telemetry\Adapter\None as NoTelemetry; -use Utopia\Telemetry\Gauge; +use Utopia\Telemetry\UpDownCounter; /** * Redis\Multiplexing adapter. @@ -33,7 +33,7 @@ class Multiplexing implements Adapter, TelemetryFeature */ private Lock $sendLock; - private ?Gauge $pendingDepth = null; + private ?UpDownCounter $pendingDepth = null; /** * @param string $host @@ -70,14 +70,14 @@ class Multiplexing implements Adapter, TelemetryFeature } /** - * Wire a telemetry adapter for connection-level metrics. The current - * pending-queue depth is recorded after each enqueue — a steady-state - * non-zero value means callers are queueing faster than Redis is - * replying. + * Wire a telemetry adapter for connection-level metrics. The pending-queue + * depth is tracked as an up/down counter — incremented on enqueue and + * decremented on dequeue — so a steady-state non-zero value means callers + * are queueing faster than Redis is replying. */ public function setTelemetry(Telemetry $telemetry): void { - $this->pendingDepth = $telemetry->createGauge( + $this->pendingDepth = $telemetry->createUpDownCounter( 'cache.redis_multiplexing.pending.depth', description: 'Pending response channels awaiting RESP frames on the multiplexed connection.', ); @@ -228,7 +228,7 @@ class Multiplexing implements Adapter, TelemetryFeature $error = null; $context->pending->enqueue($response); - $this->pendingDepth?->record($context->pending->count()); + $this->pendingDepth?->add(1); try { $context->client->send(Client::encode($args)); } catch (ConnectionException $sendError) { @@ -340,6 +340,7 @@ class Multiplexing implements Adapter, TelemetryFeature while (! $context->pending->isEmpty()) { $ch = $context->pending->dequeue(); if ($ch instanceof Channel) { + $this->pendingDepth?->add(-1); $ch->push(new ConnectionError($error)); } } @@ -411,6 +412,7 @@ class Multiplexing implements Adapter, TelemetryFeature // A complete frame implies a prior pending enqueue. $waiting = $context->pending->isEmpty() ? null : $context->pending->dequeue(); if ($waiting instanceof Channel) { + $this->pendingDepth?->add(-1); $waiting->push($value); } else { // Should never happen given the send-lock invariant. Log