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] 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); + } +}