Download the PHP package cboxdk/laravel-telemetry-insights without Composer

Cbox Telemetry Insights

The stateful half of observability for Laravel — an issue ledger, incident correlation, alerting and digests, on top of cboxdk/laravel-telemetry-ui.

The dashboard is a read-only window onto Tempo, Loki and Prometheus. It queries your telemetry stores and writes nothing to them, which is a checkable property rather than a slogan. This package adds the things that need to remember something — and keeps them in four tables of its own, so that property survives.

The problem it solves

A cache node dies at 02:14. Your application does not report "the cache is down". It reports:

Four fingerprints, four places in the code, four alerts, none of which mentions the cache. Whoever is on call spends twenty minutes deciding which of four unrelated-looking bugs to chase.

They are one event, and this package says so:

It can do that because it knows what a Laravel app is: which spans are outbound calls, which attributes identify an instance, and which of them was failing.

Highlights

• Issue ledger — every error group plus the decision your team made: open, resolved, ignored, snoozed, set from one artisan command or your own code. A resolved group that fires again is a regression, detected automatically and reopened.
• Spike detection — a known issue firing several times harder than in the window before, with guards so small numbers and brand-new issues do not masquerade as one.
• Incident correlation — errors that started together, folded into one event with a named cause, ranked evidence and a confidence you can check. When the dashboard has discovered an exporter watching the failing dependency, the incident asks it too: not just "your calls failed" but "and the cache says it was out of memory".
• Alerting that means something — rules on new issues and incidents, not only on numbers; with error rate, p95, throughput and any metric as the escape hatch. Cooldowns so one broken thing pages you once, and an unreachable backend that never reads as a breach.
• Digests — what is worth looking at this week, ranked, each finding carrying the route, statement or instance that identifies it. Including the queries that are individually fast but run a thousand times.
• A brief for your assistant — --markdown prints the findings as one self-contained document, ready to paste in with the repository open.
• Slack, webhook or your own channel — one method to implement, no SDK.
• Act where you read — resolve, snooze, ignore or acknowledge from a menu on the dashboard row, or over HTTP from your own screen. Both behind the dashboard's own gate.
• Inert when idle — boot registers class-strings only; one env var disables it entirely.

Install

PHP 8.3+, Laravel 12 or 13. No connections to configure — it reads through the dashboard's.

The three jobs put themselves on your scheduler. See the quickstart.

Does it need the dashboard UI?

It needs the dashboard's read layer — contracts, drivers, query IR — and that is a hard dependency. It does not need the dashboard to be served: an app running TELEMETRY_UI_ENABLED=false still gets the full scan, correlation and alerting. Everything that knows the UI exists lives in one folder behind a check, and an architecture test keeps it there. See architecture.

Documentation

Full documentation lives in docs/:

• Installation · Requirements
• Core concepts: architecture · issues · incidents · alerting · digests
• Cookbook: notify Slack · hand findings to an assistant
• Extending: notification channels · your own correlation · HTTP API
• Configuration reference · what this package stores · testing

Development

License

MIT — see LICENSE.md.