Reference
Reference
The canonical catalog. Metric names follow the base package's convention
(lowercase, dot-namespaced; . becomes _ in Prometheus, so
statamic.static_cache.operations scrapes as
statamic_static_cache_operations_total).
Span attributes
All on the request root span unless noted. Attributes are per-span, so their cardinality is unconstrained — ids and slugs are fine here (unlike metric labels).
| Attribute | Where | Example |
|---|---|---|
statamic.type |
root | entry, term, taxonomy |
statamic.entry.id / statamic.term.id |
root | the id |
statamic.collection |
root | blog |
statamic.blueprint |
root | article |
statamic.taxonomy |
root | topics |
statamic.site |
root + every span (ambient context) | default |
statamic.static_cache |
root | hit, miss, write |
user.roles |
root | editor,author (sorted, comma-joined) |
user.groups |
root | staff |
user.super |
root | true (present only when super) |
statamic.blink.hits / statamic.blink.misses |
root (tally) | 53 / 21 |
http.route |
root + request metric label (overridden) | entry:blog.article, term:topics, taxonomy:topics — the logical content route (see below) |
http.route.template |
root (when overridden) | /{segments?} — the raw Laravel template |
cache.key.group |
base cache spans | stache.index, stache.item, stache.meta, static_cache, app |
view.path / view.engine |
view.render spans (opt-in) |
resources/views/blog/show.antlers.html, antlers |
antlers.tag |
antlers:{tag} spans (opt-in) |
collection, partial (bounded) |
antlers.method |
antlers:{tag} spans (opt-in) |
blog, components/hero (unbounded) |
user.id, user.type and user.guard come from the base
package; the addon adds the three role/group/super attributes on top.
Request span naming
Every Statamic frontend request runs through one catch-all route, so the
base package's default METHOD /route/{pattern} name collapses to a
single value. The addon renames the root span from the resolved content:
| Content | Span name |
|---|---|
| Entry | GET entry:{collection}.{blueprint} |
| Term | GET term:{taxonomy} |
| Taxonomy index/listing | GET taxonomy:{taxonomy} |
| Frontend URL that resolves to nothing (404) | GET not_found |
Glide image (/img/asset/{container}/…) |
GET glide:{container} (glide:path / glide:url for the other two routes) |
| Anything else (a real Laravel route, the CP) | base package default |
These are exactly the data types Statamic serves as frontend pages
(everything that reaches ResponseCreated via a DataResponse: entries,
structured-collection pages, taxonomy terms, taxonomy index pages).
Assets, globals and navigations are not frontend-routable — they are
files and template data, injected into views rather than served as their
own pages — so they never get a span name. Their edits are still counted
by statamic.content.changes.
Names are bounded — collection/blueprint/taxonomy handles, never ids
or slugs; the specifics ride along as attributes (statamic.entry.id,
statamic.content.title, statamic.content.url,
statamic.content.edit_url). A static cache hit answers before the
controller resolves anything, so nothing is captured for it — the addon then
looks the URL up itself (one Stache uri-index hit, once per request) and a
hit is named and attributed exactly like a miss, plus
statamic.static_cache: hit. The same logical route is written to
http.route (below).
http.route is the logical content route
Every frontend request matches the same catch-all template
(/{segments?}), so left alone the base package's http.route label
collapses every page into one series — route tables and latency
histograms show a single bucket. The addon uses the base package's
resolveRouteUsing() hook to override http.route with the logical
content route (entry:{collection}.{blueprint} / term:{taxonomy} /
taxonomy:{taxonomy}), so the whole ecosystem — the UI route table,
Grafana, TraceQL — groups by content with no per-consumer change:
histogram_quantile(0.95, sum by (le, http_route) (
rate(http_server_request_duration_milliseconds_bucket{http_route=~"(entry|term|taxonomy):.*"}[5m])
))
The value is bounded (collections and taxonomies are a fixed set),
which is why the addon — not the base package — owns it: only the addon
knows these names are safe as a metric label. The raw Laravel template is
preserved as http.route.template for debugging.
Frontend 404s become not_found. A URL that matches the catch-all but
resolves to no entry/term/taxonomy (broken links, bots, stale sitemaps)
is bucketed as http.route = not_found instead of /{segments?}, so 404
traffic can be seen and sized separately rather than diluting the catch-all.
The not_found fallback is scoped to Statamic's FrontendController — a
404 on a real Laravel route keeps its own http.route.
Cache hits are named too. Because the addon resolves the URL when the
cache answered first, a statically-cached page carries the same http.route
as an uncached one — a route table shows one row per collection, not a
"cache hits" bucket on the catch-all — with statamic.static_cache: hit to
tell them apart.
Metrics
| Metric | Type | Labels | Source event |
|---|---|---|---|
statamic.static_cache.operations |
counter | operation: hit, miss, write, invalidate, flush |
cacher subclass overrides |
statamic.stache.warms |
counter | — | StacheWarmed |
statamic.stache.clears |
counter | — | StacheCleared |
statamic.stache.warm_duration |
histogram (s, own buckets 0.05–300 s) | — | StacheWarmed + Stache::buildTime() |
statamic.glide.generations |
counter | preset (ad-hoc params → custom) |
GlideImageGenerated |
statamic.glide.cache_clears |
counter | scope: all, asset |
GlideCacheCleared, GlideAssetCacheCleared |
statamic.forms.submissions |
counter | form |
SubmissionCreated |
statamic.content.changes |
counter | type, action |
40+ content events (see below) |
statamic.search.index_updates |
counter | index |
SearchIndexUpdated |
statamic.auth.events |
counter | event (see below) |
10 auth/2FA events |
statamic.entries.count |
gauge (opt-in) | collection |
scrape-time query |
statamic.assets.count |
gauge (opt-in) | container |
scrape-time query |
statamic.users.count |
gauge (opt-in) | — | scrape-time query |
The base package's cache.operations counter additionally carries the
key_group label from the addon's classifier when
telemetry.instrument.cache is on.
Annotation events
Unsampled telemetry events (OTLP log records) that the bundled Statamic dashboard renders as annotation lines — so latency spikes map to their cause at a glance, the same way they map to deploys.
| Event | Attributes | Source event |
|---|---|---|
statamic.cache.purge |
cache.type: stache, static, glide, glide_asset; cache.trigger: cli, http |
StacheCleared, StaticCacheCleared, GlideCacheCleared, GlideAssetCacheCleared |
A purge explains the slow requests that follow it: a stache clear means
index rebuilds, a static cache clear means full renders, a glide clear
means image regeneration. cache.trigger separates deploy-pipeline
purges (cli) from CP or MCP-triggered ones (http).
Content audit log
Every content change is also one statamic.content.change event (an OTLP
log record, correlated to the request or command that made it) — the row
behind the bounded statamic.content.changes counter. laravel-telemetry-ui
lists them on Statamic → Content as an audit log.
| Attribute | Values |
|---|---|
statamic.content.type |
entry, term, asset, collection, taxonomy, blueprint, fieldset, nav, nav_tree, collection_tree, global_set, global_variables, form, user, role, user_group, asset_container, asset_folder, site, revision, submission, … |
statamic.content.action |
created, updated, saved (nothing measurably changed), published, unpublished, deleted, uploaded, replaced, reuploaded, schedule_reached; revisions: working, revision, publish, unpublish, restore |
statamic.content.id / .title / .handle / .slug |
what an editor recognises the item by |
statamic.collection / statamic.taxonomy / statamic.asset.container / statamic.form / statamic.blueprint |
the item's home |
statamic.site |
the localisation (for a site record: the site itself; statamic.site.locale beside it) |
statamic.content.status |
an entry's status after the save |
statamic.content.url / statamic.content.path / statamic.content.edit_url |
the public URI, an asset's path, the absolute CP edit link |
statamic.content.changed |
the top-level field handles an update changed — names, never values |
statamic.revision.message / statamic.revision.key |
a revision's message and key |
statamic.content.origin |
cp, api, web, console (+ process.command) |
user.id / user.name |
the signed-in editor; the name can be switched off, the email is never sent |
Statamic fires several events for one save — EntryCreated then
EntrySaved, and re-saves an entry's localisations after it — so the record
keeps to what an editor did: the creation is one created row, and a save
Statamic made as a side effect of another (EntrySaved::isInitial()) is no
row at all. Publish transitions and changed fields come from Statamic's dirty
state; with a Stache cache store that hands back its cached instance (an
unserialised array store), that state is already synced by the time the
event fires, and the row says saved rather than guessing.
Sites are saved all at once: Statamic writes the whole sites config and
fires SiteSaved for every site, with no dirty state. When the CP's sites
form is submitted the addon takes a snapshot first, so only the sites that
changed become rows — created, updated (with the changed keys: name,
url, locale, lang, attributes, …) or deleted — with the site's
handle as statamic.site, its statamic.site.locale and URL. A sites save
made from code has nothing to compare against and is one saved row for
the batch.
statamic.content.changes labels
type and action are derived from the event class name
(AssetReplaced → asset/replaced). Subscribed families: entries,
terms, localized terms, assets (saved, deleted, uploaded, replaced,
reuploaded, references-updated), asset folders and containers, collections
and their trees, taxonomies, globals (GlobalVariablesSaved — the actual
content edit — as well as the set), navs and their trees, forms, users,
roles, groups, blueprints, fieldsets, sites, deleted submissions. Two
carry explicit labels: EntryScheduleReached → entry/schedule_reached,
DuplicateIdRegenerated → duplicate_id/regenerated.
Entry saves are special. Instead of a flat saved, an EntrySaved
is labelled by the entry's publish status at save time — published,
draft, scheduled or expired — so content.changes{type=entry}
shows the publish-state mix of editing (how much live vs draft content is
being touched). It is a status snapshot, not a transition: Statamic has
already synced the pre-save published value away by the time the event
fires, so a true publish/unpublish can't be detected reliably at the event
boundary. EntryDeleted stays entry/deleted.
Authentication metrics
The Laravel auth lifecycle — login, logout, failed, lockout,
password_reset, registered, verified — is emitted by the base
package as auth.events{event, guard} (with the guard dimension). The
failed/lockout spikes are the credential-attack signal. The addon's
statamic.auth.events (below) covers only the Statamic-specific events
the base package doesn't know about.
statamic.auth.events labels
impersonation_started, impersonation_ended, user_registered,
password_changed, two_factor_enabled, two_factor_disabled,
two_factor_challenged, two_factor_failed, two_factor_passed,
two_factor_recovery_code_replaced. No user ids on the metric — identity
lives on the request trace via user.*.
Config
config/statamic-telemetry.php. All instrument.* flags are also settable
via STATAMIC_TELEMETRY_* env vars (see the published config).
| Key | Default | Effect |
|---|---|---|
enabled |
true | Master switch for the whole overlay |
instrument.user |
true | user.roles/groups/super |
instrument.site_context |
true | statamic.site ambient dimension |
instrument.content |
true | Root span naming + entry/term attributes |
instrument.static_cache |
true | Cacher subclass swap, outcomes, header strip |
instrument.stache |
true | Cache-key classifier, warm/clear metrics |
instrument.glide |
true | Generation + cache-clear counters |
instrument.cache_purges |
true | statamic.cache.purge annotation event per cache clear |
instrument.forms |
true | Submission counter |
instrument.content_events |
true | Content-change counter |
instrument.content_audit |
true | One statamic.content.change audit record per change (needs content_events) |
instrument.search |
true | Search index-update counter |
instrument.auth |
true | Auth/security event counter |
instrument.blink |
true | Blink memoization tallies |
instrument.views |
false | A view.render detail span per rendered view |
instrument.antlers |
false | A detail span per Antlers tag (forces statamic.antlers.tracing on) |
gauges.enabled |
false | Inventory gauges (query on every scrape) |
audit.actor_name |
true | The editor's user.name beside user.id on audit records |
audit.changed_fields |
true | The changed field handles (names only) on updated records |
cp.url |
— | Turns the "Telemetry" nav item back into a link-out (Grafana / a remote laravel-telemetry-ui), an opt-out from the native pages. Unset → the native Telemetry pages |
cp.ignore_own_routes |
true | Keep the telemetry pages' own requests (and their calls to the backend) out of the app's traces and metrics |
cp.entry_tab |
true | Add the full-width Telemetry tab to every entry blueprint |
cp.audit.url |
— | The backend's query URL for every Control Panel page — Loki, Tempo and Prometheus APIs under one base (telemetryd / an LGTM gateway). Falls back to TELEMETRY_UI_LOGS_URL. No URL → empty states, no audit rows |
cp.audit.token |
— | Bearer token for the logs backend. Falls back to TELEMETRY_UI_TOKEN |
cp.audit.tenant |
— | X-Scope-OrgID tenant for a multi-tenant backend. Falls back to TELEMETRY_UI_LOGS_TENANT |
cp.audit.service |
app's | service.name to match; defaults to telemetry.service.name |
cp.audit.service_label |
service_name |
The Loki stream label the service landed on |
cp.audit.selector |
— | A full LogQL stream selector, overriding the one built from service/service_label |
cp.audit.window |
24h |
Default look-back window (1h, 24h, 7d, 30d) |
cp.audit.limit |
1000 | Newest-N records pulled from the backend before filtering in PHP |
cp.audit.timeout |
5 | Request timeout to the logs backend, in seconds |
cp.audit.enabled |
auto | Force the page off; otherwise on when a URL resolves |
Control Panel pages
The native pages — Overview, Explore, the Activity pages (Requests, Jobs,
Queries, Exceptions, Outgoing HTTP), the Statamic pages (Static cache,
Stache, Glide, Forms, Content with the audit trail), the Telemetry doctor,
the trace drawer and the entry's Telemetry tab — are documented in
Control Panel: what each shows, which
backend API it reads, the permissions, and what degrades when the backend
lacks a feature. They read the backend on cp.audit.url; metrics-backed
tiles need the app to run with a shared metric store (TELEMETRY_STORE=sqlite
/ redis / apcu) and php artisan telemetry:flush shipping it. Traces and
log-backed pages need no such wiring.
The telemetry fieldtype behind the entry tab can also be placed by hand in
any entry blueprint (type: telemetry); it stores nothing.
Antlers tags
For browser tracing in Antlers templates:
| Tag | Output |
|---|---|
{{ telemetry:browser }} |
traceparent meta + the RUM <script> — empty when telemetry.ingest.spans.enabled is off |
{{ telemetry:traceparent }} |
just <meta name="traceparent"> — empty when no trace is active |
Under static caching, the per-request traceparent and data-session are
stripped from cached copies by BrowserTracingReplacer (registered
automatically) so they never leak across visitors.
What is deliberately not instrumented
- Full-measure static cache hits — served by the web server, never reach PHP, so they produce no telemetry at all. Only PHP-served hits, misses and writes appear.
- Search queries — Statamic fires no query event; latency shows up on the request span. Only index updates are counted.
- Field augmentation — no core events. Its cost is visible indirectly through the Blink tallies, the Antlers tag spans and the view spans.
- Halting / lifecycle events —
FormSubmitted(a listener return cancels the submission),*Saving/*Deleting,*BlueprintFoundare payload-manipulation hooks, not outcomes. UrlInvalidated— already counted at the cacher asinvalidate.