README

Statamic overlay for cboxdk/laravel-telemetry: content-aware trace names, Stache and static-cache instrumentation, site context and user attribution — as a proper Statamic addon.

laravel-telemetry already traces requests, queries, queue jobs, cache and more. This addon teaches those traces Statamic's vocabulary:

• Request span naming — every Statamic frontend request goes through one catch-all route, so the default METHOD /route/{pattern} name collapses to a single useless value. Entry requests become GET entry:{collection}.{blueprint}, term requests GET term:{taxonomy} — bounded names, while http.route keeps the raw pattern.
• Content attributes — statamic.entry.id, statamic.collection, statamic.blueprint, statamic.taxonomy, statamic.term.id and statamic.site on the request root span.
• Site context — statamic.site as an ambient dimension on every span in the trace, propagated to queued jobs.
• User attribution — enduser.roles, enduser.groups and enduser.super for Statamic users (file or eloquent driven), on top of the core enduser.id/type/guard.
• Static cache — hit/miss/write outcome as statamic.static_cache on the root span, operation counters, and a fix for a subtle replay bug: the half-measure cacher snapshots response headers, so the addon strips the X-Trace-Id header before it is baked into the cached response and replayed to every visitor.
• Stache — cache keys classified into bounded groups (stache.index, stache.item, stache.meta, static_cache, app) so cache counters and spans don't drown in thousands of raw keys; warm/clear counters and warm duration.
• Glide, forms, content changes — counters per preset, per form, and per content type/action.
• Antlers render spans (opt-in) — a detail span per rendered view.
• Observable gauges (opt-in) — entries per collection, assets per container, user count, evaluated at scrape time.

Installation

composer require cboxdk/statamic-telemetry:^0.1.0-alpha.1

Alpha (0.1.0-alpha.1). Both packages are on Packagist. Until a stable 0.1.0 is tagged, allow alpha stability in your app's composer.json (or Composer will refuse the pre-release):

"minimum-stability": "alpha",
"prefer-stable": true

Requires PHP 8.3+, Statamic 6 and cboxdk/laravel-telemetry. Everything is on by default except Antlers view/tag spans and the gauges. Publish the config to change toggles:

php artisan vendor:publish --tag=statamic-telemetry-config

What you get

Spans & attributes

Metrics

Core cache counters additionally carry the key_group label from the classifier.

Grafana dashboard

The addon bundles a Statamic dashboard for the Grafana suite that ships with laravel-telemetry (telemetry:dashboards): static cache hit ratio and operations, Stache traffic by key group and warm duration, content changes, form submissions, Glide generations, the opt-in inventory gauges, and Tempo panels for content traces and slow uncached pages.

php artisan statamic-telemetry:dashboards            # import into http://localhost:3000
php artisan statamic-telemetry:dashboards --grafana=https://grafana.example.com --token=...
php artisan statamic-telemetry:dashboards --export=./grafana-provisioning

It carries the same telemetry tag as the core suite, so it appears as a tab alongside Overview, Requests, Jobs, etc. Panels are regenerated with python3 resources/grafana/generate.py.

Composing with your own hooks

laravel-telemetry's resolver hooks are single-slot — the last registration wins. This addon registers during boot, so if your app registers its own resolver it replaces the Statamic one. Delegate to the addon's public methods to compose:

use Cbox\StatamicTelemetry\Hooks;
use Cbox\StatamicTelemetry\Support\CacheKeys;
use Cbox\StatamicTelemetry\Support\Content;

Telemetry::resolveUserUsing(fn ($user, $guard) => [
    ...Hooks::userAttributes($user, $guard),
    'enduser.plan' => $user->plan ?? null,
]);

Telemetry::nameRequestsUsing(fn ($request, $response) =>
    $request->is('api/*') ? 'API '.$request->method() : Content::spanName($request)
);

Telemetry::classifyCacheKeysUsing(fn (string $store, string $key) =>
    str_starts_with($key, 'tenant:') ? 'tenant' : CacheKeys::classify($store, $key)
);

// The addon claims labelRequestsUsing too (for the statamic.route metric
// dimension). If your app needs its own metric labels, compose them:
Telemetry::labelRequestsUsing(fn ($request) => array_filter([
    'statamic.route' => Content::routeLabel($request),
    'plan' => $request->user()?->plan,
], fn ($v) => $v !== null));

Design notes

• Static cache drivers are subclassed, not decorated. Statamic's middleware and replacers use instanceof FileCacher/ApplicationCacher checks to pick code paths; a decorator would silently change static caching behaviour. The addon re-registers the file and application drivers as tracing subclasses. Custom cacher drivers are not instrumented.
• Full-measure hits are invisible. With the full strategy, cached hits are served by the web server and never reach PHP — those requests produce no telemetry at all. Only PHP-served hits, misses and writes are recorded.
• Cache hits keep the generic span name. A static cache hit never reaches the frontend controller, so there is no entry to name the span by — hit traces are GET /{pattern} with statamic.static_cache: hit (and are fast). Content-named spans are the renders.
• Latency metrics break down by content. The base http.route metric label is the catch-all template — one bucket for the whole front end. The addon adds a bounded statamic.route label so http.server.request.duration splits per collection/taxonomy. See docs/design-notes.
• Trace header stripping. The core package already skips the trace id header on Cache-Control: public responses (CDN caches). Statamic's half-measure cacher decides cacheability by its own rules and snapshots headers regardless, so the addon removes the header just before the snapshot — first visitors keep their header on file-measure, dynamic responses always keep it.
• Augmentation is observed indirectly. Statamic fires no events around field augmentation, so there is no direct per-field instrumentation. Its cost shows up in three places instead: the Blink tallies (augmentation memoization lives in Blink), the opt-in antlers:{tag} spans (tags are where augmentation work runs), and the opt-in view.render spans. Per-field visibility would need an upstream hook in statamic/cms.
• Search queries are not counted. Statamic fires SearchIndexUpdated for index writes (counted) but no event for queries — query latency is visible on the request span.
• Telemetry never throws into the app. The resolver hooks run inside laravel-telemetry's FailSafe; every event listener extends a GuardedListener base that wraps its body in the same guard. A broken listener can never break the entry save, upload or login it observes. Listeners also check their config toggle at event time, so toggles work at runtime and in tests.

More detail — the full metric/attribute/config catalog and the rationale behind each design decision — lives in docs/.

UI

None yet — the addon is structured as a regular Statamic addon (AddonServiceProvider), so CP nav, widgets and routes can be added later without restructuring.

Testing

composer install
composer check   # pint + phpstan + pest

The test suite uses Statamic's AddonTestCase and Telemetry::fake(). Note for addon/package authors: after swapping in the fake, re-register the hooks (Hooks::register($fake)) — the boot-time registrations landed on the manager the fake replaces. See tests/TestCase.php::fakeTelemetry().