Download the PHP package cboxdk/statamic-telemetry without Composer

Statamic Telemetry

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 — user.roles, user.groups and user.super for Statamic users (file or eloquent driven), on top of the core user.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

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

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.

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 php resources/grafana/generate.php.

The addon adds a Telemetry item to the Control Panel nav pointing at your telemetry UI — the in-app cboxdk/laravel-telemetry-ui dashboard automatically when installed (it has Statamic pages), or set STATAMIC_TELEMETRY_UI_URL for Grafana / a remote UI.

Browser tracing in Antlers

laravel-telemetry's browser RUM (@cboxdk/telemetry-browser) in Antlers templates — drop it in your layout <head>:

Both are empty when the span ingest (TELEMETRY_INGEST_SPANS) or the trace is off. Static caching is handled: the per-request traceparent and data-session are stripped from cached pages by a Statamic replacer (like the CSRF one), so a cache hit never replays one visitor's server trace or analytics session to everyone — the RUM self-roots instead. Full-measure (file) hits are served without PHP, so they get a self-rooted browser trace with no server span; the strip happens once when the file is compiled. See docs/browser-tracing.

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:

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.
• http.route is the content route. Left alone, every frontend page shares the /{segments?} catch-all, so route tables and latency histograms collapse into one bucket. The addon uses the base package's resolveRouteUsing() hook to override http.route with the bounded logical route (entry:blog.article, taxonomy:topics), so the UI route table, Grafana and TraceQL all group by content — no per-tool change. The raw template is kept as http.route.template. Frontend 404s (broken links, bots) bucket as not_found instead of /{segments?}; cache hits stay /{segments?} (served before any content resolves — and fast). 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

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().