Laravel Horizon Prometheus Exporter

After installation, publish the configuration file to your application using the following Artisan command. You can then customize the exporter settings in config/horizon-exporter.php.

php artisan vendor:publish --provider=LKDevelopment\\HorizonPrometheusExporter\\HorizonPrometheusExporterServiceProvider

You can visualize your Horizon metrics using a pre-made dashboard available in the Grafana Marketplace.

Dashboard ID: 11034

Install the package using Composer to enable exposing Laravel Horizon metrics to Prometheus.

composer require lkaemmerling/laravel-horizon-prometheus-exporter

The IPWhitelistingMiddleware can be used to restrict access to the Prometheus metrics endpoint by allowing only specific IP addresses or ranges.

To enable this, you must configure the horizon-exporter.ip_whitelist key in your Laravel configuration. If the configuration is empty or not set, the middleware allows all requests. If the configuration contains values, the middleware checks the incoming request's IP against the whitelist using Symfony's IpUtils. If the IP does not match, it returns a 403 Forbidden response.

// Example configuration in config/horizon-exporter.php
return [
    'ip_whitelist' => [
        '127.0.0.1',
        '192.168.1.0/24',
        '10.0.0.5',
    ],
];

The horizon_status metric is a Prometheus Gauge that reports the operational state of Laravel Horizon. The value of the gauge is determined by the status of the master supervisors:

• -1: Inactive (no master supervisors found).
• 0: Paused (at least one master supervisor is in a 'paused' state).
• 1: Running (all master supervisors are active and not paused).

The metric uses the namespace defined in your horizon-exporter.namespace configuration setting.

The RecentJobs exporter provides a Prometheus Gauge metric named horizon_recent_jobs. This metric represents the total count of recent jobs processed by Laravel Horizon.

It uses the horizon-exporter.namespace configuration value to determine the metric's namespace. The value is retrieved from the JobRepository::countRecent() method in Laravel Horizon.

To customize the exporter's behavior, you can publish the configuration file to your application's config directory using the following Artisan command. This allows you to manage settings like whether the exporter is enabled and which middleware to apply to the metrics routes.

php artisan vendor:publish --tag=config

The exporter provides a configuration option wipe_storage_after_render to control whether the Prometheus registry is cleared after the metrics are rendered and returned.

• If set to true, the registry is wiped immediately after the response is generated. This is useful for preventing memory growth or ensuring that metrics are only collected once per scrape if using certain storage backends.
• If set to false (default), the metrics remain in the registry until the next time they are overwritten or the process restarts.

// In your config/horizon-exporter.php
'wipe_storage_after_render' => true,

The package uses a configuration file named horizon-exporter.php. Two key settings control the exporter's availability and security:

• enabled: A boolean that determines if the Prometheus metrics routes are registered. If set to false, the routes will not be available.
• middleware: An array of middleware to be applied to the metrics routes. This is useful for adding authentication or IP whitelisting to protect your metrics endpoint.

The CurrentWorkload exporter provides a Prometheus Gauge metric named horizon_current_workload. This metric tracks the current workload (number of jobs) across all Laravel Horizon queues.

Metric Details:

• Type: Gauge
• Name: horizon_current_workload
• Help Text: Current workload of all queues
• Labels: queue (the name of the specific queue)
• Namespace: Uses the value configured in horizon-exporter.namespace.

The exporter automatically handles both standard workloads and workloads with split_queues, ensuring that individual queue lengths are reported as separate time series labeled by their queue name.

# Example Prometheus output format
# HELP horizon_current_workload Current workload of all queues
# TYPE horizon_current_workload gauge
horizon_exporter_queue_name{queue="default"} 15
horizon_exporter_queue_name{queue="high"} 2