Skip to content

An open-source, self-hostable PaaS alternative to Vercel, Heroku & Netlify that lets you easily deploy static sites, databases, full-stack applications and 360+ one-click services on your own servers.

feat(analytics): use Sentinel resource scope for exact unique visitors

Andras Bacsai8d6871d1c746
diff --git a/app/Livewire/Analytics.php b/app/Livewire/Analytics.php
index 2ebc6dc78f..9135147876 100644
--- a/app/Livewire/Analytics.php
+++ b/app/Livewire/Analytics.php
@@ -331,7 +331,8 @@ class Analytics extends Component
}
[$from, $to] = $this->window();
- // A selected application or service is queried under all of its Sentinel keys.
+ // A selected application or service is queried in Sentinel's resource scope, or under
+ // all of its keys on an older Sentinel.
$resource = $this->selectedResource();
$servers = $this->targetServers();
$domainForKey = fn (string $key): ?string => $this->appMeta($key)['domain'];
@@ -345,10 +346,9 @@ class Analytics extends Component
$client = $this->trafficClient($server);
if ($resource !== null) {
- $keys = $client->prefetchResource($resource->uuid(), $from, $to, $this->breakdownDimensions, $this->range);
- foreach ($keys as $key) {
- $aggregator->collect($client, $key, $from, $to, $this->range, $domainForKey);
- }
+ // One server in Sentinel's resource scope is exact; a merge across servers
+ // or the per-key fallback of an older Sentinel stays approximate.
+ $aggregator->collectResource($client, $resource->uuid(), $from, $to, $this->range, $domainForKey);
continue;
}
diff --git a/app/Livewire/Project/Application/TrafficOverview.php b/app/Livewire/Project/Application/TrafficOverview.php
index 86a6ff64f4..6cc30605a0 100644
--- a/app/Livewire/Project/Application/TrafficOverview.php
+++ b/app/Livewire/Project/Application/TrafficOverview.php
@@ -37,14 +37,19 @@ class TrafficOverview extends Component
if ($this->enabled && $server) {
try {
$client = app(SentinelTrafficClient::class, ['server' => $server]);
- // Compose services and previews record under their own keys; sum all of them.
- $keys = $client->resourceKeys($this->application->uuid);
[$from, $to] = SentinelTrafficClient::rangeWindow('24h');
- if (count($keys) > 1) {
- $client->prefetchAppOverviews($keys, $from, $to);
+ // Compose services and previews record under their own keys. Sentinel's resource
+ // scope merges them exactly; an older Sentinel gets every key summed here.
+ $overview = $client->tryResourceOverview($this->application->uuid, $from, $to);
+ if ($overview === null) {
+ $keys = $client->resourceKeys($this->application->uuid);
+ if (count($keys) > 1) {
+ $client->prefetchAppOverviews($keys, $from, $to);
+ }
+ $overviews = array_map(fn (string $key) => $client->overview($key, $from, $to), $keys);
+ $overview = TrafficAnalyticsAggregator::sumOverviews($overviews)['overview'];
}
- $overviews = array_map(fn (string $key) => $client->overview($key, $from, $to), $keys);
- $this->overview = TrafficAnalyticsAggregator::sumOverviews($overviews)['overview']->toArray();
+ $this->overview = $overview->toArray();
} catch (\Throwable $e) {
$this->overview = null;
}
diff --git a/app/Livewire/Project/Shared/ResourceTrafficAnalytics.php b/app/Livewire/Project/Shared/ResourceTrafficAnalytics.php
index 7ba0829855..a8a750f17e 100644
--- a/app/Livewire/Project/Shared/ResourceTrafficAnalytics.php
+++ b/app/Livewire/Project/Shared/ResourceTrafficAnalytics.php
@@ -14,8 +14,8 @@ use Livewire\Component;
/**
* Traffic analytics tab of one resource (Application or Service). A resource can record
- * under several Sentinel keys (compose services, previews); every key is fetched and
- * merged into one view.
+ * under several Sentinel keys (compose services, previews). Sentinel's resource scope
+ * merges them exactly; an older Sentinel gets every key fetched and merged here.
*/
abstract class ResourceTrafficAnalytics extends Component
{
@@ -124,14 +124,10 @@ abstract class ResourceTrafficAnalytics extends Component
[$from, $to] = SentinelTrafficClient::rangeWindow($this->range);
$client = app(SentinelTrafficClient::class, ['server' => $resource->server()]);
- // Resolve every key of this resource and warm all of them in one or two
- // docker execs; the per-call methods below then read from cache.
- $keys = $client->prefetchResource($resource->uuid(), $from, $to, $this->breakdownDimensions, $this->range);
-
+ // Sentinel's resource scope merges every key exactly in one docker exec. An older
+ // Sentinel falls back to all keys of the resource, merged here (approximate).
$aggregator = new TrafficAnalyticsAggregator($this->breakdownDimensions);
- foreach ($keys as $key) {
- $aggregator->collect($client, $key, $from, $to, $this->range, fn (string $appKey) => $resource->domainForKey($appKey));
- }
+ $aggregator->collectResource($client, $resource->uuid(), $from, $to, $this->range, fn (string $appKey) => $resource->domainForKey($appKey));
$result = $aggregator->overview();
$this->overview = $result['overview']->toArray();
diff --git a/app/Services/SentinelTrafficClient.php b/app/Services/SentinelTrafficClient.php
index 74e70367dd..cbbf9f971c 100644
--- a/app/Services/SentinelTrafficClient.php
+++ b/app/Services/SentinelTrafficClient.php
@@ -17,6 +17,21 @@ class SentinelTrafficClient
/** Record separator (0x1E) framing the batched curl responses in warm(). */
private const RECORD_SEPARATOR = "\x1e";
+ /**
+ * Seconds to remember that this server's Sentinel has no `/api/resource/...` routes. Longer
+ * than the data cache: every probe on an older Sentinel costs one or two wasted execs.
+ */
+ public const RESOURCE_SCOPE_ABSENCE_TTL = 300;
+
+ /** Path segment of the per-key routes: `/api/app/{key}/traffic/...`. */
+ private const SCOPE_APP = 'app';
+
+ /**
+ * Path segment of the resource routes: `/api/resource/{uuid}/traffic/...`. Sentinel merges
+ * `{uuid}` and every `{uuid}-*` key exactly (HLL union for uniques, merged t-digests).
+ */
+ private const SCOPE_RESOURCE = 'resource';
+
/** @var array<int, string> */
private const ALLOWED_DIMENSIONS = [
'status', 'method', 'country', 'referer', 'browser', 'os', 'device', 'protocol', 'scheme', 'tls', 'cache', 'bot', 'agent', 'ip', 'useragent',
@@ -28,9 +43,15 @@ class SentinelTrafficClient
// (e.g. "2024-01-14T10:00:00Z"), confirmed against sentinel/API.md.
public function overview(?string $appKey, string $from, string $to): TrafficOverviewData
{
- $json = json_decode($this->raw($this->overviewUrl($appKey, $from, $to)), true) ?? [];
+ return $this->fetchOverview($this->overviewUrl($appKey, $from, $to));
+ }
- return TrafficOverviewData::fromSentinel($json);
+ /**
+ * Exact overview of one resource: every key of the resource merged by Sentinel.
+ */
+ public function resourceOverview(string $resourceUuid, string $from, string $to): TrafficOverviewData
+ {
+ return $this->fetchOverview($this->overviewUrl($resourceUuid, $from, $to, self::SCOPE_RESOURCE));
}
/**
@@ -52,16 +73,25 @@ class SentinelTrafficClient
public function paths(?string $appKey, string $from, string $to, int $limit = 50): Collection
{
- $rows = json_decode($this->raw($this->pathsUrl($appKey, $from, $to, $limit)), true) ?? [];
+ return $this->fetchPaths($this->pathsUrl($appKey, $from, $to, $limit));
+ }
- return collect($rows)->map(fn ($r) => TrafficPathData::fromSentinel($r));
+ /**
+ * Top paths of one resource. Each row keeps the real Sentinel key in its `app` field.
+ */
+ public function resourcePaths(string $resourceUuid, string $from, string $to, int $limit = 50): Collection
+ {
+ return $this->fetchPaths($this->pathsUrl($resourceUuid, $from, $to, $limit, self::SCOPE_RESOURCE));
}
public function breakdown(?string $appKey, string $dimension, string $from, string $to, int $limit = 50): Collection
{
- $rows = json_decode($this->raw($this->breakdownUrl($appKey, $dimension, $from, $to, $limit)), true) ?? [];
+ return $this->fetchBreakdown($this->breakdownUrl($appKey, $dimension, $from, $to, $limit));
+ }
- return collect($rows)->map(fn ($r) => TrafficBreakdownData::fromSentinel($r));
+ public function resourceBreakdown(string $resourceUuid, string $dimension, string $from, string $to, int $limit = 50): Collection
+ {
+ return $this->fetchBreakdown($this->breakdownUrl($resourceUuid, $dimension, $from, $to, $limit, self::SCOPE_RESOURCE));
}
/**
@@ -77,13 +107,84 @@ class SentinelTrafficClient
*/
public function series(?string $appKey, string $range = '24h'): Collection
{
- $rows = json_decode($this->raw($this->seriesUrl($appKey, $range)), true);
+ return $this->fetchSeries($this->seriesUrl($appKey, $range));
+ }
- if (! is_array($rows) || $rows === []) {
- return collect();
+ /**
+ * @return Collection<int, TrafficSeriesBucketData>
+ */
+ public function resourceSeries(string $resourceUuid, string $range = '24h'): Collection
+ {
+ return $this->fetchSeries($this->seriesUrl($resourceUuid, $range, self::SCOPE_RESOURCE));
+ }
+
+ /**
+ * False while this server's Sentinel is known to lack the resource routes; callers then
+ * use the per-key path (resourceKeys() and a merge in TrafficAnalyticsAggregator).
+ */
+ public function supportsResourceScope(): bool
+ {
+ return Cache::get($this->resourceScopeAbsenceKey()) !== true;
+ }
+
+ /**
+ * Exact overview of one resource, or null when Sentinel has no resource routes. A failed
+ * probe is remembered (see RESOURCE_SCOPE_ABSENCE_TTL), so later calls return null at once.
+ */
+ public function tryResourceOverview(string $resourceUuid, string $from, string $to): ?TrafficOverviewData
+ {
+ $url = $this->overviewUrl($resourceUuid, $from, $to, self::SCOPE_RESOURCE);
+ if (! $this->supportsResourceScope()) {
+ return null;
}
- return collect($rows)->map(fn ($r) => TrafficSeriesBucketData::fromSentinel($r));
+ $overview = $this->genuineOverview($url);
+ if ($overview === null) {
+ $this->markResourceScopeAbsent();
+
+ return null;
+ }
+
+ return TrafficOverviewData::fromSentinel($overview);
+ }
+
+ /**
+ * Warm every resource endpoint in one exec with the resource dashboard bundle. When the
+ * bundle is unavailable, batch the individual resource endpoints instead. Returns false
+ * (and remembers it) when Sentinel has no resource routes; the caller then uses the
+ * per-key path with prefetchResource().
+ *
+ * @param array<int, string> $dimensions
+ */
+ public function prefetchResourceScope(string $resourceUuid, string $from, string $to, array $dimensions, string $range, int $pathLimit = 50, int $breakdownLimit = 50): bool
+ {
+ $this->assertSafeKey($resourceUuid);
+ if (! $this->supportsResourceScope()) {
+ return false;
+ }
+
+ $bundle = $this->fetchBundle($this->dashboardUrl($resourceUuid, $from, $to, $range, $pathLimit, $breakdownLimit, 0, self::SCOPE_RESOURCE));
+ if ($bundle !== null) {
+ $this->seedFromDashboard($resourceUuid, $from, $to, $range, $dimensions, $pathLimit, $breakdownLimit, $bundle, self::SCOPE_RESOURCE);
+
+ return true;
+ }
+
+ $overviewUrl = $this->overviewUrl($resourceUuid, $from, $to, self::SCOPE_RESOURCE);
+ $this->warm([
+ ...$this->endpointUrls($resourceUuid, $from, $to, $dimensions, $range, $pathLimit, $breakdownLimit, self::SCOPE_RESOURCE),
+ $this->attributionUrl(),
+ ]);
+
+ // After a real batch, an uncached overview means the route is absent: no second probe.
+ $supported = (! $this->usesBatchableTransport() || Cache::has($this->cacheKey($overviewUrl)))
+ && $this->genuineOverview($overviewUrl) !== null;
+
+ if (! $supported) {
+ $this->markResourceScopeAbsent();
+ }
+
+ return $supported;
}
public function apps(): array
@@ -298,21 +399,90 @@ class SentinelTrafficClient
return null;
}
- try {
- $decoded = json_decode($this->raw($this->dashboardUrl($appKey, $from, $to, $range, $pathLimit, $breakdownLimit, $appsLimit)), true);
- } catch (\Throwable) {
+ $bundle = $this->fetchBundle($this->dashboardUrl($appKey, $from, $to, $range, $pathLimit, $breakdownLimit, $appsLimit));
+ if ($bundle === null) {
Cache::put($absenceKey, true, 60);
+ }
+ return $bundle;
+ }
+
+ /**
+ * Fetch one dashboard bundle, or null when the route is absent or the response is not a
+ * real bundle (no `overview` member).
+ *
+ * @return array<string, mixed>|null
+ */
+ private function fetchBundle(string $url): ?array
+ {
+ try {
+ $decoded = json_decode($this->raw($url), true);
+ } catch (\Throwable) {
return null;
}
- if (! is_array($decoded) || ! array_key_exists('overview', $decoded)) {
- Cache::put($absenceKey, true, 60);
+ return is_array($decoded) && array_key_exists('overview', $decoded) ? $decoded : null;
+ }
+ /**
+ * The decoded overview at $url, or null when the route is absent or the body is not a
+ * real overview. Sentinel always sends `requests`, also for an empty range, so a stub
+ * (`{}`) does not count as support.
+ *
+ * @return array<string, mixed>|null
+ */
+ private function genuineOverview(string $url): ?array
+ {
+ try {
+ $decoded = json_decode($this->raw($url), true);
+ } catch (\Throwable) {
return null;
}
- return $decoded;
+ return is_array($decoded) && array_key_exists('requests', $decoded) ? $decoded : null;
+ }
+
+ private function markResourceScopeAbsent(): void
+ {
+ Cache::put($this->resourceScopeAbsenceKey(), true, self::RESOURCE_SCOPE_ABSENCE_TTL);
+ }
+
+ private function resourceScopeAbsenceKey(): string
+ {
+ return 'traffic:resource-scope-absent:'.$this->server->uuid;
+ }
+
+ private function fetchOverview(string $url): TrafficOverviewData
+ {
+ return TrafficOverviewData::fromSentinel(json_decode($this->raw($url), true) ?? []);
+ }
+
+ private function fetchPaths(string $url): Collection
+ {
+ $rows = json_decode($this->raw($url), true) ?? [];
+
+ return collect($rows)->map(fn ($r) => TrafficPathData::fromSentinel($r));
+ }
+
+ private function fetchBreakdown(string $url): Collection
+ {
+ $rows = json_decode($this->raw($url), true) ?? [];
+
+ return collect($rows)->map(fn ($r) => TrafficBreakdownData::fromSentinel($r));
+ }
+
+ /**
+ * @return Collection<int, TrafficSeriesBucketData>
+ */
+ private function fetchSeries(string $url): Collection
+ {
+ $rows = json_decode($this->raw($url), true);
+
+ if (! is_array($rows) || $rows === []) {
+ return collect();
+ }
+
+ return collect($rows)->map(fn ($r) => TrafficSeriesBucketData::fromSentinel($r));
}
/**
@@ -323,18 +493,18 @@ class SentinelTrafficClient
* @param array<int, string> $dimensions
* @param array<string, mixed> $bundle
*/
- private function seedFromDashboard(?string $appKey, string $from, string $to, string $range, array $dimensions, int $pathLimit, int $breakdownLimit, array $bundle): void
+ private function seedFromDashboard(?string $appKey, string $from, string $to, string $range, array $dimensions, int $pathLimit, int $breakdownLimit, array $bundle, string $scope = self::SCOPE_APP): void
{
$put = fn (string $url, $member) => Cache::put($this->cacheKey($url), json_encode($member), 60);
- $put($this->overviewUrl($appKey, $from, $to), $bundle['overview'] ?? []);
- $put($this->pathsUrl($appKey, $from, $to, $pathLimit), $bundle['paths'] ?? []);
- $put($this->seriesUrl($appKey, $range), $bundle['series'] ?? []);
+ $put($this->overviewUrl($appKey, $from, $to, $scope), $bundle['overview'] ?? []);
+ $put($this->pathsUrl($appKey, $from, $to, $pathLimit, $scope), $bundle['paths'] ?? []);
+ $put($this->seriesUrl($appKey, $range, $scope), $bundle['series'] ?? []);
$put($this->attributionUrl(), ['attribution' => $bundle['attribution'] ?? null]);
$breakdowns = $bundle['breakdowns'] ?? [];
foreach ($dimensions as $dimension) {
- $put($this->breakdownUrl($appKey, $dimension, $from, $to, $breakdownLimit), $breakdowns[$dimension] ?? []);
+ $put($this->breakdownUrl($appKey, $dimension, $from, $to, $breakdownLimit, $scope), $breakdowns[$dimension] ?? []);
}
foreach ($bundle['apps'] ?? [] as $app) {
@@ -369,51 +539,51 @@ class SentinelTrafficClient
* @param array<int, string> $dimensions
* @return array<int, string>
*/
- private function endpointUrls(?string $appKey, string $from, string $to, array $dimensions, string $range, int $pathLimit, int $breakdownLimit): array
+ private function endpointUrls(?string $appKey, string $from, string $to, array $dimensions, string $range, int $pathLimit, int $breakdownLimit, string $scope = self::SCOPE_APP): array
{
$urls = [
- $this->overviewUrl($appKey, $from, $to),
- $this->pathsUrl($appKey, $from, $to, $pathLimit),
- $this->seriesUrl($appKey, $range),
+ $this->overviewUrl($appKey, $from, $to, $scope),
+ $this->pathsUrl($appKey, $from, $to, $pathLimit, $scope),
+ $this->seriesUrl($appKey, $range, $scope),
];
foreach ($dimensions as $dimension) {
- $urls[] = $this->breakdownUrl($appKey, $dimension, $from, $to, $breakdownLimit);
+ $urls[] = $this->breakdownUrl($appKey, $dimension, $from, $to, $breakdownLimit, $scope);
}
return $urls;
}
- private function overviewUrl(?string $appKey, string $from, string $to): string
+ private function overviewUrl(?string $appKey, string $from, string $to, string $scope = self::SCOPE_APP): string
{
- $path = $this->appScopedPath($appKey, 'overview');
+ $path = $this->appScopedPath($appKey, 'overview', $scope);
return $this->url($path, ['from' => $from, 'to' => $to]);
}
- private function pathsUrl(?string $appKey, string $from, string $to, int $limit): string
+ private function pathsUrl(?string $appKey, string $from, string $to, int $limit, string $scope = self::SCOPE_APP): string
{
- $path = $this->appScopedPath($appKey, 'paths');
+ $path = $this->appScopedPath($appKey, 'paths', $scope);
return $this->url($path, ['from' => $from, 'to' => $to, 'limit' => (int) $limit]);
}
- private function breakdownUrl(?string $appKey, string $dimension, string $from, string $to, int $limit): string
+ private function breakdownUrl(?string $appKey, string $dimension, string $from, string $to, int $limit, string $scope = self::SCOPE_APP): string
{
$this->assertSafeDimension($dimension);
- $path = $this->appScopedPath($appKey, "breakdown/{$dimension}");
+ $path = $this->appScopedPath($appKey, "breakdown/{$dimension}", $scope);
return $this->url($path, ['from' => $from, 'to' => $to, 'limit' => (int) $limit]);
}
- private function seriesUrl(?string $appKey, string $range): string
+ private function seriesUrl(?string $appKey, string $range, string $scope = self::SCOPE_APP): string
{
$range = in_array($range, ['24h', '7d', '30d'], true) ? $range : '24h';
- $path = $this->appScopedPath($appKey, 'series');
+ $path = $this->appScopedPath($appKey, 'series', $scope);
return $this->url($path, ['range' => $range]);
}
- private function dashboardUrl(?string $appKey, string $from, string $to, string $range, int $pathLimit, int $breakdownLimit, int $appsLimit): string
+ private function dashboardUrl(?string $appKey, string $from, string $to, string $range, int $pathLimit, int $breakdownLimit, int $appsLimit, string $scope = self::SCOPE_APP): string
{
$range = in_array($range, ['24h', '7d', '30d'], true) ? $range : '24h';
$query = [
@@ -429,9 +599,8 @@ class SentinelTrafficClient
return $this->url('/traffic/dashboard', $query);
}
- $this->assertSafeKey($appKey);
- return $this->url("/app/{$appKey}/traffic/dashboard", $query);
+ return $this->url($this->appScopedPath($appKey, 'dashboard', $scope), $query);
}
private function appsUrl(): string
@@ -445,16 +614,17 @@ class SentinelTrafficClient
}
/**
- * Build a traffic path, optionally scoped to a single (validated) app key.
+ * Build a traffic path, optionally scoped to a single (validated) app key, or with
+ * SCOPE_RESOURCE to a resource uuid and all of its `{uuid}-*` keys.
*/
- private function appScopedPath(?string $appKey, string $suffix): string
+ private function appScopedPath(?string $appKey, string $suffix, string $scope = self::SCOPE_APP): string
{
if ($appKey === null) {
return "/traffic/{$suffix}";
}
$this->assertSafeKey($appKey);
- return "/app/{$appKey}/traffic/{$suffix}";
+ return "/{$scope}/{$appKey}/traffic/{$suffix}";
}
/**
diff --git a/app/Services/TrafficAnalyticsAggregator.php b/app/Services/TrafficAnalyticsAggregator.php
index 8ff50dc0fa..bc50a41e57 100644
--- a/app/Services/TrafficAnalyticsAggregator.php
+++ b/app/Services/TrafficAnalyticsAggregator.php
@@ -8,6 +8,8 @@ use App\Data\Traffic\TrafficOverviewData;
* Merges Sentinel traffic data from several sources (servers, or the several app keys of
* one resource) into one view. Counters are summed; latency takes the worst value and
* uniques are summed, so both are flagged approximate once more than one source is merged.
+ * A resource on a Sentinel with resource routes is one source: Sentinel merges its keys
+ * exactly, so one server stays exact.
*/
class TrafficAnalyticsAggregator
{
@@ -73,17 +75,47 @@ class TrafficAnalyticsAggregator
*/
public function collect(SentinelTrafficClient $client, ?string $appKey, string $from, string $to, string $range, callable $domainForKey, int $limit = 50): void
{
- $this->addOverview($client->overview($appKey, $from, $to));
- $this->addPaths($client->paths($appKey, $from, $to, $limit), $appKey, $domainForKey);
+ $this->collectScope($client, $appKey, false, $from, $to, $range, $domainForKey, $limit);
+ }
+
+ /**
+ * Fetch every shape for one resource on one server and merge it in. Uses Sentinel's
+ * resource scope when the server has it (one exact source). Otherwise every key of the
+ * resource is fetched and merged as its own source, as before.
+ *
+ * @param callable(string): ?string $domainForKey resolves a path row's app key to its domain
+ */
+ public function collectResource(SentinelTrafficClient $client, string $resourceUuid, string $from, string $to, string $range, callable $domainForKey, int $limit = 50): void
+ {
+ if ($client->prefetchResourceScope($resourceUuid, $from, $to, $this->dimensions, $range, $limit, $limit)) {
+ $this->collectScope($client, $resourceUuid, true, $from, $to, $range, $domainForKey, $limit);
+
+ return;
+ }
+
+ foreach ($client->prefetchResource($resourceUuid, $from, $to, $this->dimensions, $range, $limit, $limit) as $key) {
+ $this->collect($client, $key, $from, $to, $range, $domainForKey, $limit);
+ }
+ }
+
+ /**
+ * @param callable(string): ?string $domainForKey
+ */
+ private function collectScope(SentinelTrafficClient $client, ?string $key, bool $resourceScope, string $from, string $to, string $range, callable $domainForKey, int $limit): void
+ {
+ $this->addOverview($resourceScope ? $client->resourceOverview($key, $from, $to) : $client->overview($key, $from, $to));
+ $this->addPaths($resourceScope ? $client->resourcePaths($key, $from, $to, $limit) : $client->paths($key, $from, $to, $limit), $key, $domainForKey);
foreach ($this->dimensions as $dimension) {
- $this->addBreakdown($dimension, $client->breakdown($appKey, $dimension, $from, $to, $limit));
+ $this->addBreakdown($dimension, $resourceScope
+ ? $client->resourceBreakdown($key, $dimension, $from, $to, $limit)
+ : $client->breakdown($key, $dimension, $from, $to, $limit));
}
$this->attribution ??= $client->attribution();
try {
- $this->addSeries($client->series($appKey, $range));
+ $this->addSeries($resourceScope ? $client->resourceSeries($key, $range) : $client->series($key, $range));
} catch (\Throwable) {
// Leave this source out of the series; the donut fallback covers it.
}
diff --git a/tests/Feature/TrafficAnalytics/ResourceScopeTrafficTest.php b/tests/Feature/TrafficAnalytics/ResourceScopeTrafficTest.php
new file mode 100644
index 0000000000..36ef965c08
--- /dev/null
+++ b/tests/Feature/TrafficAnalytics/ResourceScopeTrafficTest.php
@@ -0,0 +1,457 @@
+<?php
+
+use App\Livewire\Analytics as GlobalAnalytics;
+use App\Livewire\Project\Application\Analytics as ApplicationAnalytics;
+use App\Livewire\Project\Application\TrafficOverview;
+use App\Livewire\Project\Service\Analytics as ServiceAnalytics;
+use App\Models\Application;
+use App\Models\Environment;
+use App\Models\PrivateKey;
+use App\Models\Project;
+use App\Models\Server;
+use App\Models\Service;
+use App\Models\ServiceApplication;
+use App\Models\StandaloneDocker;
+use App\Models\Team;
+use App\Models\User;
+use App\Services\SentinelTrafficClient;
+use App\Services\TrafficAnalyticsAggregator;
+use Illuminate\Foundation\Testing\RefreshDatabase;
+use Illuminate\Support\Facades\Cache;
+use Livewire\Livewire;
+
+uses(RefreshDatabase::class);
+
+/**
+ * Serves canned bodies by the first needle contained in the url (insertion order) and logs
+ * every requested url across all instances, so a test can prove which routes were queried.
+ */
+class FakeResourceScopeTrafficClient extends SentinelTrafficClient
+{
+ /** @var array<int, string> */
+ public static array $requested = [];
+
+ public array $responses = [];
+
+ protected function raw(string $url): string
+ {
+ self::$requested[] = $url;
+
+ foreach ($this->responses as $needle => $response) {
+ if (str_contains($url, $needle)) {
+ if ($response instanceof Throwable) {
+ throw $response;
+ }
+
+ return $response;
+ }
+ }
+
+ return '{}';
+ }
+}
+
+function resourceScopeOverview(int $requests, int $uniques, float $p95 = 20.0): array
+{
+ return [
+ 'requests' => $requests,
+ 'bytes_in' => $requests * 10,
+ 'bytes_out' => $requests * 100,
+ 'status' => ['s2xx' => $requests, 's3xx' => 0, 's4xx' => 0, 's5xx' => 0],
+ 'latency' => ['p50' => 5.0, 'p95' => $p95, 'p99' => 50.0],
+ 'unique_visitors' => $uniques,
+ ];
+}
+
+/**
+ * Sentinel answers an absent route with 404 and an empty body; raw() then throws.
+ */
+function resourceRouteAbsent(): RuntimeException
+{
+ return new RuntimeException('Traffic analytics returned an invalid response.');
+}
+
+function bindResourceScopeFake(array $responses): void
+{
+ app()->bind(SentinelTrafficClient::class, function ($app, $params) use ($responses) {
+ $client = new FakeResourceScopeTrafficClient($params['server']);
+ $client->responses = $responses;
+
+ return $client;
+ });
+}
+
+/**
+ * @return array<int, string>
+ */
+function requestedResourceScopeUrls(string $needle): array
+{
+ return array_values(array_filter(FakeResourceScopeTrafficClient::$requested, fn (string $url) => str_contains($url, $needle)));
+}
+
+/**
+ * Canned responses for a Sentinel with the resource routes: the resource bundle and the
+ * individual resource endpoints. Every per-key route throws, so a per-key query fails the test.
+ */
+function resourceScopeResponses(string $uuid, array $overview, array $paths = []): array
+{
+ return [
+ "/resource/{$uuid}/traffic/dashboard" => json_encode([
+ 'overview' => $overview,
+ 'paths' => $paths,
+ 'breakdowns' => ['country' => [['value' => 'US', 'requests' => $overview['requests']]]],
+ 'series' => [],
+ 'attribution' => null,
+ ]),
+ "/resource/{$uuid}/traffic/overview" => json_encode($overview),
+ "/resource/{$uuid}/traffic/paths" => json_encode($paths),
+ "/resource/{$uuid}/traffic/breakdown/country" => json_encode([['value' => 'US', 'requests' => $overview['requests']]]),
+ "/resource/{$uuid}/traffic/series" => json_encode([['bucket' => 1000, 's2xx' => $overview['requests'], 'unique_visitors' => $overview['unique_visitors']]]),
+ '/app/' => new RuntimeException('per-key route must not be queried when the resource scope exists'),
+ '/traffic/apps' => new RuntimeException('the key list must not be queried when the resource scope exists'),
+ ];
+}
+
+beforeEach(function () {
+ config()->set('app.maintenance.store', 'array');
+ Cache::flush();
+ Server::flushIdentityMap();
+ FakeResourceScopeTrafficClient::$requested = [];
+
+ $this->team = Team::factory()->create();
+ $this->user = User::factory()->create();
+ $this->team->members()->attach($this->user->id, ['role' => 'owner']);
+ $this->actingAs($this->user);
+ session(['currentTeam' => $this->team]);
+
+ $this->privateKey = PrivateKey::factory()->create(['team_id' => $this->team->id]);
+ $this->server = Server::factory()->create([
+ 'team_id' => $this->team->id,
+ 'private_key_id' => $this->privateKey->id,
+ ]);
+ $this->server->settings->is_traffic_analytics_enabled = true;
+ $this->server->settings->save();
+ $this->destination = StandaloneDocker::where('server_id', $this->server->id)->first()
+ ?? StandaloneDocker::factory()->create(['server_id' => $this->server->id, 'network' => 'coolify-test']);
+
+ $this->project = Project::factory()->create(['team_id' => $this->team->id, 'name' => 'Storefront']);
+ $this->environment = Environment::factory()->create(['project_id' => $this->project->id]);
+
+ $this->application = Application::factory()->create([
+ 'name' => 'Compose Shop',
+ 'build_pack' => 'dockercompose',
+ 'fqdn' => null,
+ 'docker_compose_domains' => json_encode([
+ 'api' => ['domain' => 'https://api.shop.test'],
+ 'web' => ['domain' => 'https://www.shop.test'],
+ ]),
+ 'environment_id' => $this->environment->id,
+ 'destination_id' => $this->destination->id,
+ 'destination_type' => StandaloneDocker::class,
+ ]);
+ $this->apiKey = $this->application->uuid.'-'.traefikSafeServiceNameSegment('api');
+ $this->webKey = $this->application->uuid.'-'.traefikSafeServiceNameSegment('web');
+});
+
+/**
+ * Canned responses for an older Sentinel: resource routes are absent, per-key routes answer.
+ */
+function perKeyFallbackResponses(string $uuid, string $apiKey, string $webKey): array
+{
+ return [
+ '/resource/' => resourceRouteAbsent(),
+ '/traffic/apps' => json_encode([$apiKey, $webKey]),
+ "/app/{$apiKey}/traffic/overview" => json_encode(resourceScopeOverview(100, 10, 20.0)),
+ "/app/{$webKey}/traffic/overview" => json_encode(resourceScopeOverview(50, 8, 40.0)),
+ "/app/{$apiKey}/traffic/paths" => json_encode([['path' => '/v1/orders', 'app' => $apiKey, 'requests' => 100]]),
+ "/app/{$webKey}/traffic/paths" => json_encode([['path' => '/checkout', 'app' => $webKey, 'requests' => 50]]),
+ "/app/{$uuid}/traffic" => new RuntimeException('bare uuid must not be queried when compose keys exist'),
+ ];
+}
+
+it('builds the url of every resource endpoint', function () {
+ $client = new FakeResourceScopeTrafficClient($this->server);
+ $client->responses = ['/overview' => json_encode(resourceScopeOverview(1, 1)), '' => '[]'];
+
+ $client->resourceOverview('res-uuid', '2026-08-01T00:00:00Z', '2026-08-02T00:00:00Z');
+ $client->resourcePaths('res-uuid', 'F', 'T', 25);
+ $client->resourceBreakdown('res-uuid', 'country', 'F', 'T', 10);
+ $client->resourceSeries('res-uuid', '7d');
+ $client->prefetchResourceScope('res-uuid', 'F', 'T', [], '30d', 25, 10);
+
+ $urls = FakeResourceScopeTrafficClient::$requested;
+ expect($urls[0])->toBe('http://localhost:8888/api/resource/res-uuid/traffic/overview?from=2026-08-01T00:00:00Z&to=2026-08-02T00:00:00Z')
+ ->and($urls[1])->toBe('http://localhost:8888/api/resource/res-uuid/traffic/paths?from=F&to=T&limit=25')
+ ->and($urls[2])->toBe('http://localhost:8888/api/resource/res-uuid/traffic/breakdown/country?from=F&to=T&limit=10')
+ ->and($urls[3])->toBe('http://localhost:8888/api/resource/res-uuid/traffic/series?range=7d')
+ ->and($urls[4])->toBe('http://localhost:8888/api/resource/res-uuid/traffic/dashboard?from=F&to=T&range=30d&paths_limit=25&breakdown_limit=10');
+});
+
+it('rejects an unsafe resource uuid or dimension before any request', function () {
+ $client = new FakeResourceScopeTrafficClient($this->server);
+
+ expect(fn () => $client->resourceOverview("x'; touch /tmp/pwned; '", 'F', 'T'))->toThrow(InvalidArgumentException::class)
+ ->and(fn () => $client->prefetchResourceScope('a b', 'F', 'T', [], '24h'))->toThrow(InvalidArgumentException::class)
+ ->and(fn () => $client->tryResourceOverview('a/b', 'F', 'T'))->toThrow(InvalidArgumentException::class)
+ ->and(fn () => $client->resourceBreakdown('res', 'not-a-dimension', 'F', 'T'))->toThrow(InvalidArgumentException::class);
+ expect(FakeResourceScopeTrafficClient::$requested)->toBeEmpty();
+});
+
+it('serves every resource endpoint from one resource dashboard exec', function () {
+ $client = new class($this->server) extends SentinelTrafficClient
+ {
+ public array $fetched = [];
+
+ protected function remoteFetch(string $url): string
+ {
+ $this->fetched[] = $url;
+ if (str_contains($url, '/resource/res/traffic/dashboard')) {
+ return json_encode([
+ 'overview' => resourceScopeOverview(9, 4),
+ 'paths' => [['path' => '/', 'app' => 'res-web', 'requests' => 9]],
+ 'breakdowns' => ['country' => [['value' => 'US', 'requests' => 9]]],
+ 'series' => [['bucket' => 1000, 's2xx' => 9]],
+ 'attribution' => 'MaxMind',
+ ]);
+ }
+ throw new RuntimeException("unexpected fetch: {$url}");
+ }
+
+ protected function batchRemoteFetch(array $urls): string
+ {
+ throw new RuntimeException('no batch expected');
+ }
+ };
+
+ expect($client->prefetchResourceScope('res', 'F', 'T', ['country'], '24h'))->toBeTrue()
+ ->and($client->resourceOverview('res', 'F', 'T')->uniqueVisitors)->toBe(4)
+ ->and($client->resourcePaths('res', 'F', 'T')->first()->toArray()['app'])->toBe('res-web')
+ ->and($client->resourceBreakdown('res', 'country', 'F', 'T'))->toHaveCount(1)
+ ->and($client->resourceSeries('res', '24h'))->toHaveCount(1)
+ ->and($client->attribution())->toBe('MaxMind')
+ ->and($client->fetched)->toHaveCount(1);
+});
+
+it('falls back to one batch of individual resource endpoints when the resource dashboard is absent', function () {
+ $client = new class($this->server) extends SentinelTrafficClient
+ {
+ public int $batchCalls = 0;
+
+ protected function remoteFetch(string $url): string
+ {
+ if (str_contains($url, '/traffic/dashboard')) {
+ return '';
+ }
+ throw new RuntimeException("unexpected fetch: {$url}");
+ }
+
+ protected function batchRemoteFetch(array $urls): string
+ {
+ $this->batchCalls++;
+
+ return implode("\x1e", array_map(fn ($url) => match (true) {
+ str_contains($url, '/resource/res/traffic/overview') => json_encode(resourceScopeOverview(3, 2)),
+ str_contains($url, '/attribution') => '{"attribution":"demo"}',
+ str_contains($url, '/resource/res/traffic/') => '[]',
+ default => throw new RuntimeException("unexpected batch url: {$url}"),
+ }, $urls))."\x1e";
+ }
+ };
+
+ expect($client->prefetchResourceScope('res', 'F', 'T', ['country'], '24h'))->toBeTrue()
+ ->and($client->batchCalls)->toBe(1)
+ ->and($client->resourceOverview('res', 'F', 'T')->requests)->toBe(3)
+ ->and($client->attribution())->toBe('demo');
+ $client->resourceBreakdown('res', 'country', 'F', 'T');
+});
+
+it('remembers absent resource routes and does not probe them again within the ttl', function () {
+ $client = new class($this->server) extends SentinelTrafficClient
+ {
+ public int $remoteFetches = 0;
+
+ public int $batchCalls = 0;
+
+ protected function remoteFetch(string $url): string
+ {
+ $this->remoteFetches++;
+
+ return '';
+ }
+
+ protected function batchRemoteFetch(array $urls): string
+ {
+ $this->batchCalls++;
+
+ return implode("\x1e", array_fill(0, count($urls), ''))."\x1e";
+ }
+ };
+
+ expect($client->prefetchResourceScope('res', 'F', 'T', ['country'], '24h'))->toBeFalse()
+ ->and($client->prefetchResourceScope('res', 'F', 'T', ['country'], '24h'))->toBeFalse()
+ ->and($client->tryResourceOverview('res', 'F', 'T'))->toBeNull()
+ ->and($client->remoteFetches)->toBe(1)
+ ->and($client->batchCalls)->toBe(1)
+ ->and($client->supportsResourceScope())->toBeFalse();
+
+ $this->travel(SentinelTrafficClient::RESOURCE_SCOPE_ABSENCE_TTL + 1)->seconds();
+
+ expect($client->supportsResourceScope())->toBeTrue();
+});
+
+it('queries an application once in the resource scope, with exact uniques and no approximate badges', function () {
+ $paths = [
+ ['path' => '/v1/orders', 'app' => $this->apiKey, 'requests' => 100],
+ ['path' => '/checkout', 'app' => $this->webKey, 'requests' => 50],
+ ];
+ bindResourceScopeFake(resourceScopeResponses($this->application->uuid, resourceScopeOverview(150, 12, 30.0), $paths));
+
+ $component = loadLazy(Livewire::test(ApplicationAnalytics::class, ['application' => $this->application]))
+ ->assertOk()
+ ->assertSet('latencyApproximate', false)
+ ->assertSet('uniquesApproximate', false)
+ ->assertDontSee('double-counted')
+ ->assertDontSee('not a true merged percentile');
+
+ $instance = $component->instance();
+ $paths = collect($instance->topPaths)->keyBy('path');
+ expect($instance->overview['requests'])->toBe(150)
+ ->and($instance->overview['uniqueVisitors'])->toBe(12)
+ ->and($instance->overview['latencyP95'])->toBe(30.0)
+ ->and($paths['/v1/orders']['domain'])->toBe('api.shop.test')
+ ->and($paths['/checkout']['domain'])->toBe('www.shop.test')
+ ->and(requestedResourceScopeUrls('/resource/'.$this->application->uuid.'/traffic/overview'))->toHaveCount(1)
+ ->and(requestedResourceScopeUrls('/app/'))->toBeEmpty()
+ ->and(requestedResourceScopeUrls('/traffic/apps'))->toBeEmpty();
+});
+
+it('queries a service in the resource scope with no approximate badges', function () {
+ $service = Service::factory()->create([
+ 'name' => 'Umami',
+ 'server_id' => $this->server->id,
+ 'destination_id' => $this->destination->id,
+ 'destination_type' => $this->destination->getMorphClass(),
+ 'environment_id' => $this->environment->id,
+ ]);
+ foreach (['web' => 'https://app.svc.test', 'admin' => 'https://admin.svc.test'] as $name => $fqdn) {
+ ServiceApplication::create(['service_id' => $service->id, 'name' => $name, 'image' => 'nginx:alpine', 'fqdn' => $fqdn]);
+ }
+ $adminKey = $service->uuid.'-'.traefikSafeServiceNameSegment('admin');
+ bindResourceScopeFake(resourceScopeResponses($service->uuid, resourceScopeOverview(320, 7), [
+ ['path' => '/login', 'app' => $adminKey, 'requests' => 20],
+ ]));
+
+ $component = loadLazy(Livewire::test(ServiceAnalytics::class, ['service' => $service]))
+ ->assertOk()
+ ->assertSee('admin.svc.test')
+ ->assertSet('latencyApproximate', false)
+ ->assertSet('uniquesApproximate', false);
+
+ expect($component->instance()->overview['uniqueVisitors'])->toBe(7)
+ ->and(requestedResourceScopeUrls('/app/'))->toBeEmpty();
+});
+
+it('falls back to the per-key merge with approximate badges when Sentinel lacks the resource routes', function () {
+ bindResourceScopeFake(perKeyFallbackResponses($this->application->uuid, $this->apiKey, $this->webKey));
+
+ $component = loadLazy(Livewire::test(ApplicationAnalytics::class, ['application' => $this->application]))
+ ->assertOk()
+ ->assertSet('latencyApproximate', true)
+ ->assertSet('uniquesApproximate', true)
+ ->assertSee('double-counted');
+
+ expect($component->instance()->overview['requests'])->toBe(150)
+ ->and($component->instance()->overview['uniqueVisitors'])->toBe(18)
+ ->and($component->instance()->overview['latencyP95'])->toBe(40.0);
+
+ $probes = count(requestedResourceScopeUrls('/resource/'));
+ expect($probes)->toBeGreaterThan(0);
+
+ // The absence is cached: a refresh within the ttl goes straight to the per-key path.
+ $component->call('loadData')->assertSet('uniquesApproximate', true);
+ loadLazy(Livewire::test(TrafficOverview::class, ['application' => $this->application]))->assertOk();
+
+ expect(requestedResourceScopeUrls('/resource/'))->toHaveCount($probes);
+});
+
+it('shows the resource overview in the application traffic card', function () {
+ bindResourceScopeFake(resourceScopeResponses($this->application->uuid, resourceScopeOverview(4200, 33)));
+
+ $component = loadLazy(Livewire::test(TrafficOverview::class, ['application' => $this->application]))
+ ->assertOk()
+ ->assertSee('4,200');
+
+ expect($component->instance()->overview['uniqueVisitors'])->toBe(33)
+ ->and(requestedResourceScopeUrls('/resource/'))->toHaveCount(1)
+ ->and(requestedResourceScopeUrls('/traffic/dashboard'))->toBeEmpty();
+});
+
+it('sums the keys in the application traffic card when Sentinel lacks the resource routes', function () {
+ bindResourceScopeFake(perKeyFallbackResponses($this->application->uuid, $this->apiKey, $this->webKey));
+
+ loadLazy(Livewire::test(TrafficOverview::class, ['application' => $this->application]))
+ ->assertOk()
+ ->assertSee('150');
+});
+
+it('uses the resource scope when the global analytics filter selects a resource', function () {
+ bindResourceScopeFake([
+ ...resourceScopeResponses($this->application->uuid, resourceScopeOverview(150, 12)),
+ '/traffic/overview' => json_encode(resourceScopeOverview(999, 99)),
+ ]);
+
+ $component = loadLazy(Livewire::withQueryParams(['app' => $this->application->uuid])->test(GlobalAnalytics::class))
+ ->assertOk()
+ ->assertSet('appUuid', $this->application->uuid)
+ ->assertSet('latencyApproximate', false)
+ ->assertSet('uniquesApproximate', false);
+
+ expect($component->instance()->overview['requests'])->toBe(150)
+ ->and($component->instance()->overview['uniqueVisitors'])->toBe(12)
+ ->and(requestedResourceScopeUrls('/app/'))->toBeEmpty()
+ ->and(requestedResourceScopeUrls('/traffic/apps'))->toBeEmpty();
+});
+
+it('keeps the unfiltered leaderboard on per-key rows without resource queries', function () {
+ bindResourceScopeFake([
+ '/resource/' => new RuntimeException('the leaderboard must not query the resource scope'),
+ '/traffic/apps' => json_encode([$this->apiKey, $this->webKey]),
+ "/app/{$this->apiKey}/traffic/overview" => json_encode(resourceScopeOverview(100, 10)),
+ "/app/{$this->webKey}/traffic/overview" => json_encode(resourceScopeOverview(50, 8)),
+ '/traffic/overview' => json_encode(resourceScopeOverview(150, 15)),
+ ]);
+
+ $instance = loadLazy(Livewire::test(GlobalAnalytics::class))->assertOk()->instance();
+
+ expect($instance->topApps[0]['uuid'])->toBe($this->application->uuid)
+ ->and($instance->topApps[0]['requests'])->toBe(150)
+ ->and($instance->overview['uniqueVisitors'])->toBe(15)
+ ->and(requestedResourceScopeUrls('/resource/'))->toBeEmpty();
+});
+
+it('keeps a merge of one resource across several servers approximate', function () {
+ $otherServer = Server::factory()->create(['team_id' => $this->team->id, 'private_key_id' => $this->privateKey->id]);
+ $uuid = $this->application->uuid;
+
+ $first = new FakeResourceScopeTrafficClient($this->server);
+ $first->responses = resourceScopeResponses($uuid, resourceScopeOverview(100, 10, 20.0));
+ $second = new FakeResourceScopeTrafficClient($otherServer);
+ $second->responses = resourceScopeResponses($uuid, resourceScopeOverview(50, 5, 40.0));
+
+ $aggregator = new TrafficAnalyticsAggregator(['country']);
+ $aggregator->collectResource($first, $uuid, 'F', 'T', '24h', fn () => null);
+ $aggregator->collectResource($second, $uuid, 'F', 'T', '24h', fn () => null);
+
+ $result = $aggregator->overview();
+ expect($result['overview']->requests)->toBe(150)
+ ->and($result['overview']->uniqueVisitors)->toBe(15)
+ ->and($result['latencyApproximate'])->toBeTrue()
+ ->and($result['uniquesApproximate'])->toBeTrue()
+ ->and(requestedResourceScopeUrls('/app/'))->toBeEmpty();
+
+ // One server in the resource scope is exact.
+ $single = new TrafficAnalyticsAggregator(['country']);
+ $single->collectResource($first, $uuid, 'F', 'T', '24h', fn () => null);
+ expect($single->overview()['latencyApproximate'])->toBeFalse()
+ ->and($single->overview()['uniquesApproximate'])->toBeFalse();
+});