Spatie Laravel Prometheus

The spatie/laravel-prometheus package allows you to export application metrics to Prometheus. It provides a mechanism to register custom metrics and includes built-in support for Laravel queues and Horizon.

Metrics are exposed via the /prometheus endpoint. You can configure your Prometheus instance to scrape this endpoint periodically and use tools like Grafana to visualize the data. The package also supports adding a security layer to the /prometheus endpoint to prevent sensitive metrics from being publicly accessible.

Prometheus::addGauge('User count')
    ->value(fn() => User::count());

A collector is a class used to bundle and register metrics, making it easy for package authors to provide metrics to their users.

To create a collector, you must implement the Spatie\Prometheus\Collectors\Collector interface, which requires a register() method. Inside this method, you use the Prometheus facade to define and register your metrics (such as gauges, counters, etc.).

namespace Spatie\Prometheus\Collectors;

interface Collector
{
    public function register(): void;
}

The package provides built-in collectors to monitor Laravel queues, including metrics for queue sizes, pending jobs, and delayed jobs. It supports all Laravel queue drivers (Redis, Database, SQS, etc.).

To enable these collectors, use the registerQueueCollectors method. You must provide an array of queue names and the name of the queue driver being used.

Note: If you are using Laravel Horizon, use the Horizon collectors instead of these queue collectors.

// Enable all queue collectors
$this->registerQueueCollectors(['high', 'normal', 'low'], 'redis');

Once you have created a collector class, you need to tell the Prometheus package to use it. You can do this by calling the registerCollectorClasses() method on the Prometheus facade, typically within a Laravel Service Provider's register or boot method. Pass an array of the collector class names to be registered.

// in a service provider

use Spatie\Prometheus\Facades\Prometheus;
use Spatie\Prometheus\Collectors\Horizon\CurrentMasterSupervisorCollector;

Prometheus::registerCollectorClasses([
    CurrentMasterSupervisorCollector::class,
]);

To visualize your Laravel metrics using the hosted Grafana service, you must install the Grafana Agent on your server. The agent acts as a bridge, scraping the /prometheus endpoint of your Laravel application and pushing that data to Grafana.com.

Setup Steps:

1. Create a free account at grafana.com.
2. Launch your Grafana instance from the account dashboard.
3. Navigate to Connections and add a new connection of type Hosted prometheus Metrics.
4. Select Via Grafana Agent when prompted.
5. Follow the wizard to install the agent and generate a configuration file.
6. To ensure the agent remains running on your server, use a process manager like Supervisord or, if using Laravel Forge, create a daemon.

You can export application-specific metrics by registering them using the Prometheus facade. For example, to export a gauge representing a count that changes over time (like a user count), use addGauge and provide a callback function to the value method that returns the current value.

Metrics are exposed via the /prometheus endpoint. It is recommended to add a security layer to this endpoint to prevent sensitive metrics from being publicly accessible.

Prometheus::addGauge('User count')
    ->value(fn() => User::count());

To export key Laravel Horizon metrics to Prometheus, you must manually enable the Horizon collectors within your app/Providers/PrometheusServiceProvider.php file.

Uncomment the $this->registerHorizonCollectors(); method call inside the register method of the provider.

Once Prometheus is running, you need to tell Grafana how to access it as a data source:

1. Open Grafana at http://your-server-ip:3000.
2. Log in (default credentials: admin / admin).
3. Navigate to Data Sources via the gear icon on the left sidebar.
4. Click Add data source and select Prometheus.
5. Set the following configuration:
   • Name: Prometheus
   • Type: Prometheus
   • URL: http://localhost:9090 (assuming Prometheus is running on the same server).
6. Save the data source.

After installing via Composer, run the following Artisan command to publish the configuration file (config/prometheus.php) and register the PrometheusServiceProvider.

php artisan prometheus:install

If you are using Laravel Horizon, you can export specific metrics including supervisor status, workload distribution, job throughput, and failure rates using the built-in Horizon collectors.

To enable these, use the registerHorizonCollectors method.

// Enable all Horizon collectors
$this->registerHorizonCollectors();