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 <noreply@anthropic.com>
This commit is contained in:
loks0nandClaude Opus 4.7 committed 2026-05-19 15:14:37 +01:00
1 parent ece1f4d11e
commit 6e84e3c8a5
2 files changed
+83 -1

No files matched your search

+17 -1
View File
@@ -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;
@@ -0,0 +1,66 @@
<?php
namespace Utopia\Tests\Unit;
use PHPUnit\Framework\TestCase;
use Utopia\Cache\Adapter\Memory;
use Utopia\Cache\Cache;
use Utopia\Telemetry\Adapter\Test as TestTelemetry;
class LoadResultsTelemetryTest extends TestCase
{
public function testLoadEmitsHitAndMissCounts(): void
{
$cache = new Cache(new Memory());
$telemetry = new TestTelemetry();
$cache->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<int, array<string, mixed>> $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<int, array<string, mixed>> $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);
}
}