Statamic Telemetry Laravel Package

Technical Evaluation

Architecture fit. The package remains a producer-only instrumentation adapter: it observes Statamic lifecycle events and emits telemetry through cboxdk/laravel-telemetry. v3.1.0 broadens that role materially. It now emits a content audit stream — one statamic.content.change event per content change — into the logs backend, covering entries, terms, assets, collections, taxonomies, blueprints, fieldsets, navigations, trees, global sets, users, roles, groups, forms, sites, and revisions. It still owns no storage, transport, or query layer, but the blast radius is larger: audit records are more likely to be used for compliance, investigations, and content-ops support than metrics are. The privacy boundary is deliberate and good — field handles but never values, user id and optional name but never email — but it still puts titles, handles, URLs, CP edit links, actor names, and source context into the logging estate. Treat this as two capabilities in one package: operational telemetry and content audit. The statamic.stache.warm_duration bucket change is a corrective architectural alignment: the histogram now has seconds-appropriate bounds rather than inheriting millisecond-era defaults, which fixes a known percentile-quality problem for hosts with pre-3.0 published config.

Integration feasibility. Mechanically still a composer bump, but v3.1.0 is not only a dependency bump. The content audit log is on by default, so integration now includes a security/privacy review, retention and access policy for the logs backend, volume estimation, and a decision on audit.actor_name. The audit log can be disabled with STATAMIC_TELEMETRY_CONTENT_AUDIT=false, so a phased rollout is possible. The UI listing on Statamic → Content requires laravel-telemetry-ui 3.1; the CP nav fix supports both 2.x and later. The statamic.content.change span now carries the save action rather than the counter label; the statamic.content.changes counter is unchanged, so metric dashboards survive, but custom span-attribute queries may not. The bucket change is config-level but has a one-window transition where old bucket counts are read against new bounds.

Technical risk. The v3.0.0 unit change remains the dominant risk for any estate not yet fully on 3.x: statamic.stache.warm moved from milliseconds to seconds, and nothing warns at runtime because a duration a thousand times too small is still a valid duration. v3.1.0 adds three risks. First, audit-log default-on can create unexpected data collection, log volume, and retention cost; the safeguards are good but not a substitute for a policy decision. Second, audit completeness has intentional gaps: side-effect saves, such as localisation saves triggered by another entry save, produce no row, and sites saved from code produce one saved row while CP site saves produce one row per changed site. Those semantics are defensible but must be documented, or investigators will treat the audit log as more complete than it is. Third, the span action semantic change can silently break any dashboard or alert keyed on statamic.content.change span attributes, even though the counter is preserved. The bucket change is lower risk but still produces one meaningless percentile window after deploy.

Key questions.

• Do we hold a metric catalogue that records units, or is unit knowledge tribal and embedded in each dashboard?
• Who are the named owners of every dashboard, alert, and recording rule referencing statamic.stache.warm, and can we enumerate them before merge rather than after?
• Is there a mixed-version window where some environments emit seconds and others milliseconds under the same metric name? How do we scope queries by service version or deployment to avoid meaningless aggregates?
• Does any downstream system persist or re-export statamic.stache.warm — recording rules writing to a derived table, long-term storage with its own schema — making the correction a data fix rather than a config fix?
• Are there SLOs or contractual SLAs computed from this metric, which would turn a silent threshold error into a reporting obligation?
• For the content audit log: what is the lawful basis, retention period, and access model for statamic.content.change records in the logs backend?
• Is audit.actor_name permitted in our jurisdictions and by our internal privacy policy, or should it be disabled?
• What log-volume increase do we expect from content audit events, and does the logs backend retention match the audit retention requirement?
• Are the intentional audit gaps — side-effect saves omitted, site code-save semantics — acceptable to compliance and content operations?
• Who consumes the statamic.content.change span attributes, and will the action semantic change break their queries?
• Are we upgrading laravel-telemetry-ui to 3.1, and do we need the Content page at launch?
• What is the rollback story for both the package and the audit-log enablement flag?

Integration Approach

Stack fit. Strong fit for a Laravel/Statamic estate already moving to the semantic-conventions release of cboxdk/laravel-telemetry. The audit log is a natural extension of the telemetry package’s event-observation model, and making it switchable is the right operational posture. The bucket correction is idiomatic and removes a host-config trap that made warm-duration percentiles unreliable. The main stack caveat is that content audit is a compliance-adjacent capability, not just observability; it should be reviewed by whoever owns privacy, security, and log retention, not only by platform engineering.

Migration path. There are two paths.

From 2.x to 3.1.x: treat it as the v3.0 migration plus the v3.1 audit-log rollout. Upgrade core telemetry to ^3.0, apply the ÷1000 correction to every statamic.stache.warm consumer in the same change set where possible, deploy the package, then enable and validate the audit log under an approved configuration. The unit correction should not wait for the audit-log review.

From 3.0.x to 3.1.x: bump the package, review the default-on audit log, decide STATAMIC_TELEMETRY_CONTENT_AUDIT and audit.actor_name, upgrade laravel-telemetry-ui to 3.1 if the Content page is in scope, and monitor the first histogram window. Test the audit log against real content operations: create, update, publish, unpublish, delete, asset upload/replace, site change, and a revision save. Confirm that a side-effect localisation save produces no extra row and that a CP sites save produces one row per changed site.

Compatibility. Core ^3.0 remains a prerequisite; an environment still on core 2.x cannot resolve this release and will fail loudly at build time. The audit UI requires laravel-telemetry-ui 3.1. The CP nav fix supports 2.x and later, so the missing-nav bug is closed. Mixed-version risk still applies to statamic.stache.warm: old dashboards against new emitters are valid queries returning wrong numbers, and vice versa. A new mixed-version risk applies to audit coverage: environments with the audit log enabled and environments without it will produce different completeness in a central logs backend. Scope by deployment or service version, and do not treat a central audit query as fleet-complete during a staggered rollout.

Sequencing.

1. Confirm the fleet is on cboxdk/laravel-telemetry ^3.0.
2. Complete privacy/security review for the content audit log: retention, access, audit.actor_name, and whether the flag is enabled at launch.
3. Upgrade laravel-telemetry-ui to 3.1 if the Content page is required.
4. Deploy v3.1.0 to a canary with audit logging enabled per the approved config.
5. Verify audit records for each resource family and each action; check for side-effect duplicate rows and confirm the documented gaps.
6. Monitor log volume and retention impact before fleet-wide enablement.
7. If coming from 2.x, land corrected statamic.stache.warm thresholds and dashboards in the same change set as the dependency bump, or gate them behind deployment-version-aware queries.
8. Verify statamic.stache.warm_duration after the first full window: the old bucket counts should settle against the new 0.05 s–300 s bounds. Spot-check one real warm against wall-clock timing.
9. Broadcast the audit-log behaviour and opt-out flag to on-call, content operations, and dashboard owners.

Operational Impact

Maintenance. Moderate increase. The metric path remains low-maintenance and now better aligned with upstream conventions, but the content audit log adds a schema-like surface: new Statamic events, resource coverage, actor and source fields, and intentional exclusions. The package will need to keep pace with Statamic lifecycle changes across many content types. Dependency bumps remain paired with the telemetry core. Audit retention and access rules become an ongoing operational responsibility, not a one-time configuration.

Support. Higher than the v3.0 change alone. The metric-unit failure mode is still invisible to monitoring and visible to humans, so the first signal may be a human asking why a latency panel looks impossibly good or why an alert stopped firing. The audit log adds a different support load: content teams and compliance users will ask why a change is missing, why a site save produced multiple rows, why a localisation save produced none, and who can see actor names. Pre-empt with a short runbook and a broadcast that includes the runtime-silence caveat for the unit change and the audit-log semantics. The CP nav fix removes a prior source of confusion for laravel-telemetry-ui 2.x+ users.

Scaling. Metrics remain neutral: cardinality, emit frequency, and payload size are unchanged; the histogram bucket change adds no meaningful cost. The content audit log is not neutral. Every content change emits an event with multiple dimensions — item id, title, handle, collection/taxonomy/container, site, URL, CP edit link, action, field handles, user id, optional user name, and source. Volume scales with editorial activity, and log-backend storage and retention costs scale with that volume. High-cardinality fields such as item ids and URLs may also affect log query performance. Estimate volume from current content-change rates before fleet-wide enablement.

Failure modes.

• Silent metric miscalibration remains the top risk if any consumer still treats statamic.stache.warm as milliseconds. A p95 panel flatlines near zero and looks like an improvement; an upper-bound alert at > 500 now means > 500 s and never fires.
• Silent alert storm is less likely but possible for lower-bound rules that now fire continuously.
• Unexpected audit data collection: the audit log is on by default, so an unreviewed rollout can place actor names, titles, URLs, and CP links into the logs backend without an approved retention or access policy.
• Audit incompleteness: side-effect saves are intentionally omitted, and site saves have different row semantics depending on CP versus code. Investigators may over-trust the log.
• Span-attribute breakage: statamic.content.change action now means the save action, not the counter label; custom span queries may break while the counter remains healthy.
• Bucket transition: the first window after deploy reads old bucket counts against the new 0.05 s–300 s bounds, so warm-duration percentiles are temporarily meaningless before settling.
• Mixed audit coverage: during a staggered rollout, a central audit query is incomplete across environments, which is a compliance risk rather than a performance risk.
• Hard install failure on core 2.x remains loud and therefore benign.
• Correction drift: someone “fixes” a dashboard back to the old millisecond threshold after the fact and silently reintroduces the unit bug.

Ramp-up. Small for engineers, larger for the organisation than v3.0 alone. The code change is still a composer bump, and the metric correction is a known half-day to a few days of discovery and dashboard work. The audit log adds review time for privacy, security, and content operations, plus training on what the audit log does and does not contain. Assign separate owners: one for the producer-side dependency bump, one for the statamic.stache.warm consumer audit, and one for the content-audit policy and rollout. Do not consider the change complete until a real warm measurement has been reconciled against wall-clock timing and a real content change has been verified end-to-end in the audit log.