Weave Code
Laravel Prometheus Laravel Package
spatie/laravel-prometheus
Export key Laravel app metrics to Prometheus via an easy metric registry and a /prometheus endpoint. Ships with built-in queue and Horizon metrics, plus an optional security layer to keep sensitive data private. Visualize the results in Grafana.
spatie/laravel-prometheus exports key metrics from your Laravel app to Prometheus, which can then be visualized with Grafana. Register metrics with a fluent API—for instance, Prometheus::addGauge('User count')->value(fn() => User::count())—and they're served at the /prometheus endpoint for Prometheus to scrape periodically.
- Fluent gauges with lazy, closure-based values
- Out-of-the-box metrics for Laravel queues and Horizon
- Optional security layer to keep metrics private
- Simple
/prometheusendpoint for scraping - Seamless Grafana dashboards
Frequently asked questions about Laravel Prometheus
- How do I install and set up spatie/laravel-prometheus in a Laravel app?
- Install it with Composer using composer require spatie/laravel-prometheus, then publish the package config file so you can adjust the endpoint and middleware settings. Register your metrics, typically in a service provider, through the Prometheus facade. Metrics are then rendered at the /prometheus route in the Prometheus text exposition format. No sidecar, agent, or push gateway is required, but an existing Prometheus server must be able to reach the endpoint.
- Which Laravel and PHP versions does spatie/laravel-prometheus support?
- Version 1.5.0 requires PHP 8.4 or higher and Laravel 12 or higher, and it is a native fit for Laravel 11/12/13-era applications on modern PHP. Support moves forward aggressively with little overlap: 1.4.0 dropped Laravel 10, and 1.5.0 dropped older PHP and Laravel releases. Check the release notes before upgrading, and pin the version that matches your framework and PHP baseline.
- How do I secure the /prometheus endpoint, and can I change its path?
- Yes, the endpoint is configurable in the package config file, so you can move it off the default /prometheus path. Security is handled by middleware: you assign your own middleware to the route, which is the single most important control here since the package has no auth, tenancy, or RBAC model of its own. Middleware wiring was corrected in 1.0.3, so use a recent release. For production, also restrict the route at the ingress or load balancer so metrics are not publicly reachable.
- How do I register a custom gauge or counter with the Prometheus facade?
- Metrics are declared declaratively, for example Prometheus::addGauge('User count')->value(fn () => User::count()). Values are resolved lazily through closures at scrape time rather than when the metric is registered, so keep those closures cheap. Counter support was added in 1.2.0 alongside gauges. Register your collectors in a service provider so they are available on every scrape.
- Does spatie/laravel-prometheus include queue and Horizon metrics out of the box?
- Yes. The package ships with collectors for Laravel queues and for Horizon, and vanilla queue instrumentation landed in 1.3.0. This is where most of the immediate value sits for a typical Laravel app, since queue depth and failed-job visibility are common monitoring blind spots. Decide whether your app uses Horizon or plain queues, because the collector you rely on depends on that choice.
- Do the metric closures run on every scrape, and can they slow down my app?
- Yes. Every metric closure executes synchronously during a scrape, so a gauge that runs User::count() on a large table or a collector that touches Redis or Horizon turns a monitoring request into real production load. A slow or failing closure degrades the whole scrape, not just that single metric. Budget a p99 latency for the /prometheus endpoint and keep every closure cheap and exception-safe.
- How do I avoid high cardinality and a Prometheus metrics explosion?
- Cardinality is entirely the adopter's problem: the package provides no guardrails against labelling metrics by user ID, request path, or other unbounded values. Define a naming and labelling convention up front and review new metrics before they ship. Keep label sets small and bounded, and prefer aggregates over per-entity labels. Cardinality explosions are the classic Prometheus failure mode and here they are one careless line of code away.
- How do I test Prometheus metrics in a Laravel test suite?
- The simplest approach is a feature test that hits the /prometheus route and asserts the response body contains the expected metric names and values in the text exposition format. You can also unit test the closure behind a metric by invoking it directly with controlled data. Keep test fixtures small so scrape-time queries stay fast in CI. Because values resolve lazily, remember that assertions reflect state at request time, not at registration time.
- Is spatie/laravel-prometheus actively maintained, and how do I handle breaking changes?
- It is a single-vendor Spatie package at roughly 290 GitHub stars, with a maintenance-grade release cadence driven largely by dependency bumps and Laravel version compatibility. Collector naming and semantics are still settling: 1.6.0 renamed FailedJobsPerHourCollector to FailedRecentJobsCollector, which can break dashboards and alerts that depend on metric names. Pin versions in composer.json and review changelogs before absorbing minor upgrades, since breaking changes have shipped in minor releases.
- What are the alternatives to spatie/laravel-prometheus if I don't already run Prometheus?
- This package presumes an existing Prometheus server that can scrape your app, so adopting it means committing to Prometheus and Grafana, including retention and alerting. If you are standardised on push-based or vendor APM such as Datadog, New Relic, or Sentry, those tools already cover much of the same ground. Laravel Pulse and Telescope are lighter-weight options for in-app visibility, while lower-level Prometheus client libraries exist if you need more control. Sequence the package behind the observability platform decision, not in front of it.
Weaver
How can I help you explore Laravel packages today?