Weave Code
Statamic Telemetry Laravel Package
cboxdk/statamic-telemetry
A Statamic addon that brings lightweight telemetry to your site, capturing usage and performance data you can review from the control panel. Laravel-native, configurable, and quick to install via Composer for insight into how your site and content are used.
Statamic Telemetry is a lightweight diagnostics addon for Statamic CMS that exposes anonymous, aggregated data about your installation—such as core, PHP, and addon versions—via a single endpoint. Built for maintainers and agencies, it helps you understand which versions and configurations are in use without collecting personally identifiable information, and it can be enabled or disabled per environment.
- Collects core, PHP, and addon version data automatically
- Anonymous and aggregated—no PII or site content
- Simple JSON endpoint for easy inspection and aggregation
- Configurable per environment with sensible defaults
- Works out of the box with the Statamic control panel
Frequently asked questions about Statamic Telemetry
- What does cboxdk/statamic-telemetry do?
- It is a Statamic addon that layers content-aware instrumentation on top of the cboxdk/laravel-telemetry core. It emits trace names that reflect the content actually being rendered, instruments Stache warming and static-cache behaviour, and attaches site context and user attribution to the telemetry it produces. The package is a producer only: it owns no storage, transport, or query layer, so everything it records flows through the telemetry core to your existing backend.
- How do I install cboxdk/statamic-telemetry?
- Install it with Composer alongside the telemetry core, for example composer require cboxdk/statamic-telemetry. Version 3.x requires cboxdk/laravel-telemetry ^3.0, so resolve both in a single lockfile update rather than bumping them separately. There is no data migration, schema change, or config migration step; the addon hooks Statamic lifecycle events and begins emitting metrics once the core has a backend configured.
- Which Laravel and Statamic versions does this package support?
- The authoritative answer is the require block in the package composer.json, since Statamic addons declare their Laravel and Statamic constraints there. Version 3.0 additionally pins cboxdk/laravel-telemetry to ^3.0, the release aligned with OpenTelemetry semantic conventions for durations. Environments still on 2.x of the core cannot resolve this release at all, which fails loudly at build time and is therefore the safe failure mode.
- Why did statamic.stache.warm change from milliseconds to seconds in v3.0.0?
- OpenTelemetry semantic conventions define durations in seconds, so staying on milliseconds progressively isolates this metric from conforming backends, dashboard templates, and auto-instrumentation sources. Because the conversion happens at the record call, the value is divided rather than relabelled, so the metric name stays stable while its meaning changes. The upgrade itself is just a Composer constraint bump on both sides; the real work is rescaling every consumer of the metric.
- Will upgrading to 3.0 break my existing dashboards and alerts?
- Nothing fails at runtime, which is exactly the risk: a duration that is a thousand times too small is still a valid duration. A p95 Stache warm panel will flatline near zero and look like a spectacular performance improvement, while an alert threshold set at 500 (formerly 500 ms) now means 500 seconds and will never fire. Before merging, enumerate every dashboard, alert rule, recording rule, SLO definition, and notebook referencing statamic.stache.warm and divide those thresholds by 1000.
- Does this package store or export telemetry data itself?
- No. It is a thin instrumentation adapter and acts purely as a producer, emitting metrics through cboxdk/laravel-telemetry to whatever backend you have already configured. Storage, transport, sampling, and querying belong to the core package and your observability stack. That narrow scope keeps the blast radius of any upgrade small: changes are limited to the metric names and values the addon emits.
- How does this compare to Laravel Telescope or Statamic's built-in insights?
- Telescope is a development-focused debugging tool that records requests, queries, and jobs into its own storage for inspection, whereas this addon emits metrics and traces to your observability backend for ongoing production monitoring. Statamic's control panel utilities give you surface-level activity, while this package also covers front-end rendering, Stache warming, and static-cache behaviour. They are complementary: keep Telescope for local debugging and use this addon for dashboards, alerting, and trend analysis.
- What does the addon instrument in Stache and the static cache?
- It observes the Stache warm path and emits a statamic.stache.warm duration metric, which tells you how long index rebuilding and warming actually take. Static-cache instrumentation shows whether requests are served from the static cache or fall through to a full Statamic render. Together these let you separate cache-hit performance from cold-render cost without bolting on extra tooling.
- What happens if some environments emit seconds and others milliseconds for statamic.stache.warm?
- The metric name is identical in both cases, so a mixed-version estate produces an ambiguous series and any aggregate across it is garbage. Because the conversion is applied at the record call, you cannot straddle the change on the producer side, only on the consumer side. During a rolling upgrade, scope queries by service version or deployment so seconds and milliseconds are never averaged together, and finish the rollout quickly.
- How should I roll this out and what is the rollback story?
- Deploy to staging first with your real dashboards and alert rules pointed at it, then confirm Stache warm values look plausible in seconds rather than suspiciously near zero. Rollback is a Composer downgrade to 2.x, but that also reverts cboxdk/laravel-telemetry to 2.x, so you would lose the semantic-conventions alignment across the rest of your instrumentation. Fixing consumers is usually cheaper than deferring, since deferring creates a long-lived version exception that eventually has to be force-migrated under time pressure.
Weaver
How can I help you explore Laravel packages today?