Horizon Exporter Laravel Package

Technical Evaluation

Architecture fit: renoki-co/horizon-exporter is a thin instrumentation layer that exposes Laravel Horizon's queue and worker telemetry in a Prometheus-scrapeable format. It sits alongside Horizon rather than replacing it: Horizon remains the source of truth for queue state, Redis remains the backing store, and this package adds an HTTP exposition surface plus (typically) a service provider, config file, and optional route middleware. For teams already running Horizon in production and standardising on Prometheus/Grafana, the architectural fit is high and the blast radius is small — it adds a read-only endpoint, not a new runtime dependency in the request/worker path.

Integration feasibility: Low-to-moderate. Installation is Composer plus config publishing and route registration; the real work is on the observability side — scrape config, label strategy, dashboards, and alert rules. There is no data migration requirement, no schema change, and no change to how jobs are dispatched or processed, which makes this one of the cheaper integrations available.

Technical risk: The 2.0.0 release contains exactly one substantive change: Laravel v9 support, with Laravel 8.x dropped. That is a breaking change for constraint resolution only — an application pinned to Laravel 8 cannot install 2.0.x, and an application that upgrades Laravel 9→10+ later will need to confirm this package keeps pace. Secondary risks are typical of small single-maintainer Laravel packages: Horizon's internal APIs and Redis key layout are not a stability contract, so a Horizon major release can silently break metric collection, and the exported metric names/labels are effectively a public API for your dashboards and alerts once adopted.

Key questions:

1. Does our fleet run Laravel 9+ across every app we intend to instrument, or do we need to hold 1.x for Laravel 8 services and run two versions concurrently?
2. Which Horizon metrics become our SLO inputs (queue wait p95, job throughput, failed-job rate, worker saturation), and are those names stable across this package's majors?
3. Is the metrics endpoint authenticated, and can it be bound to an internal-only network path rather than the public ingress?
4. What is the maintainer's release cadence and bus factor, and do we have a fork-and-patch contingency?
5. Does the exporter's Redis access pattern add measurable load at our Horizon scale (queue count × scrape interval)?

Integration Approach

Stack fit: Designed for Laravel + Horizon + Redis, exposing metrics for Prometheus. It composes cleanly with the standard observability stack (Prometheus scrape → Grafana dashboards → Alertmanager), and does not conflict with existing APM tooling because it reports queue-state metrics rather than tracing spans. Teams without Horizon get nothing from this package; teams without Prometheus get a raw endpoint with no consumer.

Migration path: For a first-time adoption there is no migration — it is net-new instrumentation. For anyone already on 1.x, 2.0.0 is a constraint bump, not a code rewrite: update the Composer constraint, re-publish/merge the config if the route or middleware defaults changed, and re-run the metrics endpoint smoke test. Because 1.x remains installable for Laravel 8, the clean migration is by application, not by big-bang: upgrade each service's Laravel version first, then bump the exporter, so the dependency graph never has a service straddling both.

Compatibility: Effectively two tracks — 2.x for Laravel 9+, 1.x for Laravel 8. Any internal shared package, base image, or starter template that constrains renoki-co/horizon-exporter must be checked, since a shared constraint of ^1.0 will block Laravel 9 upgrades and a shared constraint of ^2.0 will block any straggler service. This is the single most likely integration friction point.

Sequencing:

1. Confirm Laravel/Horizon version inventory per application; classify each as 2.x-eligible or blocked on 1.x.
2. Trial in one non-critical service: install, bind the route internally, verify scrape success and metric cardinality.
3. Build dashboards and alert rules against real metric names before broad rollout, treating those names as a versioned contract.
4. Roll out application-by-application alongside Laravel 9 upgrades; keep the 1.x track documented as a temporary state with an owner and an exit date.
5. Only then add the exporter to base templates / service scaffolds.

Operational Impact

Maintenance: Small surface area, modest ongoing cost: a Composer update a few times a year, plus a compatibility check whenever Horizon or Laravel majors land. The disproportionate maintenance cost is not the package but the contract it creates — dashboards and alerts that must be updated if metric names or labels change. Assign that contract an owner; unowned dashboards rot fastest.

Support: Single-maintainer open-source project with a narrow scope, which cuts both ways: the code is small enough to fork and patch internally if upstream stalls, and small enough that an abandoned release is recoverable. Do not assume enterprise support or a guaranteed CVE response; treat it as community-supported and plan a fork contingency for the endpoint code specifically.

Scaling: Overhead per scrape is bounded by the number of queues and workers being enumerated, not by job volume, so cost scales with Horizon topology rather than traffic — generally favourable. The real scaling concern is cardinality: per-queue or per-supervisor labels multiplied across many services can inflate Prometheus series count and storage. Budget series count deliberately, and keep scrape intervals sane (30–60s) rather than aggressive.

Failure modes:

• Silent metric loss — exporter breaks after a Horizon upgrade, endpoint returns 500s or empty payloads, and alerting on "no data" is the only thing that catches it. Alert on scrape absence, not just on threshold breaches.
• Stale-but-green dashboards — endpoint up, values frozen or wrong, which is worse than down because it looks healthy.
• Constraint deadlock — a shared ^1.0 constraint quietly blocking a Laravel 9 upgrade across many repos.
• Endpoint exposure — metrics route reachable from public ingress, leaking queue names, job class names, and traffic patterns.
• Redis pressure — many exporters scraping the same shared Redis instance at once during a queue backlog, exactly when you least want additional load.

Ramp-up: Low for a Laravel-fluent engineer — roughly half a day to install, verify, and wire a scrape target. The longer pole is observability literacy: translating Horizon's queue semantics (wait time, supervisor balance, failed-job ratio) into meaningful SLOs and correctly-thresholded alerts. Budget one to two weeks for dashboards and alert tuning with someone who already owns on-call for those queues; without that ownership the metrics are collected but never acted on.