Horizon Configuration
Documentation
Use search-docs for detailed Horizon patterns and documentation covering configuration, supervisors, balancing, dashboard authorization, tags, notifications, metrics, and deployment.
For deeper guidance on specific topics, read the relevant reference file before implementing:
references/supervisors.md covers supervisor blocks, balancing strategies, multi-queue setups, and auto-scalingreferences/notifications.md covers LongWaitDetected alerts, notification routing, and the waits configreferences/tags.md covers job tagging, dashboard filtering, and silencing noisy jobsreferences/metrics.md covers the blank metrics dashboard, snapshot scheduling, and retention config
Basic Usage
Installation
php artisan horizon:install
Supervisor Configuration
Define supervisors in config/horizon.php. The environments array merges into defaults and does not replace the whole supervisor block:
'defaults' => [
'supervisor-1' => [
'connection' => 'redis',
'queue' => ['default'],
'balance' => 'auto',
'minProcesses' => 1,
'maxProcesses' => 10,
'tries' => 3,
],
],
'environments' => [
'production' => [
'supervisor-1' => ['maxProcesses' => 20, 'balanceCooldown' => 3],
],
'local' => [
'supervisor-1' => ['maxProcesses' => 2],
],
],
Dashboard Authorization
Restrict access in App\Providers\HorizonServiceProvider:
protected function gate(): void
{
Gate::define('viewHorizon', function (User $user) {
return $user->is_admin;
});
}
Verification
- Run
php artisan horizon and visit /horizon
- Confirm dashboard access is restricted as expected
- Check that metrics populate after scheduling
horizon:snapshot
Common Pitfalls
- Horizon only works with the Redis queue driver. Other drivers such as database and SQS are not supported.
- Redis Cluster is not supported. Horizon requires a standalone Redis connection.
- Always check
config/horizon.php before making changes to understand the current supervisor and environment configuration.
- The
environments array overrides only the keys you specify. It merges into defaults and does not replace it.
- The timeout chain must be ordered: job
timeout less than supervisor timeout less than retry_after. The wrong order can cause jobs to be retried before Horizon finishes timing them out.
- The metrics dashboard stays blank until
horizon:snapshot is scheduled. Running php artisan horizon alone does not populate metrics.
- Always use
search-docs for the latest Horizon documentation rather than relying on this skill alone.
1---2name: configuring-horizon3description: Use this skill whenever the user mentions Horizon by name in a Laravel context. Covers the full Horizon lifecycle: installing Horizon (horizon:install, Sail setup), configuring config/horizon.php (supervisor blocks, queue assignments, balancing strategies, minProcesses/maxProcesses), fixing the dashboard (authorization via Gate::define viewHorizon, blank metrics, horizon:snapshot scheduling), and troubleshooting production issues (worker crashes, timeout chain ordering, LongWaitDetected notifications, waits config). Also covers job tagging and silencing. Do not use for generic Laravel queues without Horizon, SQS or database drivers, standalone Redis setup, Linux supervisord, Telescope, or job batching.4license: MIT5---67# Horizon Configuration89## Documentation1011Use `search-docs` for detailed Horizon patterns and documentation covering configuration, supervisors, balancing, dashboard authorization, tags, notifications, metrics, and deployment.1213For deeper guidance on specific topics, read the relevant reference file before implementing:1415- `references/supervisors.md` covers supervisor blocks, balancing strategies, multi-queue setups, and auto-scaling16- `references/notifications.md` covers LongWaitDetected alerts, notification routing, and the `waits` config17- `references/tags.md` covers job tagging, dashboard filtering, and silencing noisy jobs18- `references/metrics.md` covers the blank metrics dashboard, snapshot scheduling, and retention config1920## Basic Usage2122### Installation2324```bash25php artisan horizon:install26```2728### Supervisor Configuration2930Define supervisors in `config/horizon.php`. The `environments` array merges into `defaults` and does not replace the whole supervisor block:3132<!-- Supervisor Config -->33```php34'defaults' => [35 'supervisor-1' => [36 'connection' => 'redis',37 'queue' => ['default'],38 'balance' => 'auto',39 'minProcesses' => 1,40 'maxProcesses' => 10,41 'tries' => 3,42 ],43],4445'environments' => [46 'production' => [47 'supervisor-1' => ['maxProcesses' => 20, 'balanceCooldown' => 3],48 ],49 'local' => [50 'supervisor-1' => ['maxProcesses' => 2],51 ],52],53```5455### Dashboard Authorization5657Restrict access in `App\Providers\HorizonServiceProvider`:5859<!-- Dashboard Gate -->60```php61protected function gate(): void62{63 Gate::define('viewHorizon', function (User $user) {64 return $user->is_admin;65 });66}67```6869## Verification70711. Run `php artisan horizon` and visit `/horizon`722. Confirm dashboard access is restricted as expected733. Check that metrics populate after scheduling `horizon:snapshot`7475## Common Pitfalls7677- Horizon only works with the Redis queue driver. Other drivers such as database and SQS are not supported.78- Redis Cluster is not supported. Horizon requires a standalone Redis connection.79- Always check `config/horizon.php` before making changes to understand the current supervisor and environment configuration.80- The `environments` array overrides only the keys you specify. It merges into `defaults` and does not replace it.81- The timeout chain must be ordered: job `timeout` less than supervisor `timeout` less than `retry_after`. The wrong order can cause jobs to be retried before Horizon finishes timing them out.82- The metrics dashboard stays blank until `horizon:snapshot` is scheduled. Running `php artisan horizon` alone does not populate metrics.83- Always use `search-docs` for the latest Horizon documentation rather than relying on this skill alone.
m3ue