Merge pull request #72 from utopia-php/feat-telemetry-improvements

feat: hit/miss counter + fix multiplexing pending-depth gauge
This commit is contained in:
Luke B. Silver authored and GitHub committed 2026-05-19 16:01:29 +01:00
commit 224d66c7df
3 files changed
+153 -9

No files matched your search

+10 -8
View File
@@ -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
+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 === false ? 'miss' : 'hit',
]);
return $result;
@@ -0,0 +1,126 @@
<?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);
/** @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<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);
}
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<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('any', 60);
$this->assertSame('hit', $captured[0]['result']);
}
}