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 diff --git a/src/Cache/Cache.php b/src/Cache/Cache.php index 5a9d4c5695..89c0e039d9 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 === false ? 'miss' : 'hit', ]); return $result; diff --git a/tests/Cache/Unit/LoadResultsTelemetryTest.php b/tests/Cache/Unit/LoadResultsTelemetryTest.php new file mode 100644 index 0000000000..42995e088c --- /dev/null +++ b/tests/Cache/Unit/LoadResultsTelemetryTest.php @@ -0,0 +1,126 @@ +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); + /** @phpstan-ignore-next-line property.notFound */ + $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); + } + + 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']); + } +}