Laravel Horizon - Knowledge of Laravel

What is Horizon?

Laravel Horizon is a monitoring dashboard dedicated to Laravel’s Redis queue. You can visualize job throughput, run time, and failure state in real time and manage your worker configuration in code.

Horizon is a package that extends the base queue features. Make sure you understand the fundamentals of queues and jobs before reading on. You must also use Redis as the backend.

Installation

Horizon uses Redis as its queue backend. Make sure QUEUE_CONNECTION in config/queue.php is set to redis. Redis Cluster is not currently supported.

Install via Composer.

composer require laravel/horizon

After installation, publish Horizon’s assets and configuration files.

php artisan horizon:install

This command generates config/horizon.php and app/Providers/HorizonServiceProvider.php.

Configuration

Structure of config/horizon.php

config/horizon.php is the file that manages all worker configuration. The core option is environments.

'environments' => [
    'production' => [
        'supervisor-1' => [
            'connection' => 'redis',
            'queue' => ['default', 'notifications'],
            'balance' => 'auto',
            'autoScalingStrategy' => 'time',
            'minProcesses' => 1,
            'maxProcesses' => 10,
            'balanceMaxShift' => 1,
            'balanceCooldown' => 3,
            'tries' => 3,
            'timeout' => 60,
        ],
    ],

    'local' => [
        'supervisor-1' => [
            // Other values are inherited from the defaults section
            'maxProcesses' => 3,
        ],
    ],
],

Horizon internally uses a Redis connection named horizon. Do not use this name for any other connection in config/database.php.

CSP nonce (Content Security Policy)

If you want to set a nonce attribute on the script / style tags used in Horizon’s views as part of a Content Security Policy, use the Horizon::cspNonce method. Since a new nonce is assigned per request, you’ll typically call this inside a middleware.

use Closure;
use Illuminate\Http\Request;
use Laravel\Horizon\Horizon;
use Symfony\Component\HttpFoundation\Response;

public function handle(Request $request, Closure $next): Response
{
    Horizon::cspNonce('csp-nonce');

    return $next($request);
}

Add this middleware to the middleware option in config/horizon.php.

'middleware' => [
    'web',
    App\Http\Middleware\AddHorizonCspNonce::class,
],

Supervisors

Each environment can have one or more “supervisors”. A supervisor is a management unit for a worker group; you can run multiple supervisors with different queues, balance strategies, and process counts inside the same environment.

Default values

Use the defaults option to configure default values that apply to every supervisor.

'defaults' => [
    'supervisor-1' => [
        'connection' => 'redis',
        'queue' => ['default'],
        'balance' => 'auto',
        'tries' => 1,
        'timeout' => 60,
        'maxProcesses' => 1,
    ],
],

Maintenance mode

When your application is in maintenance mode, Horizon does not process jobs by default. To force processing, use the force option.

'environments' => [
    'production' => [
        'supervisor-1' => [
            'force' => true,
        ],
    ],
],

Maximum number of attempts

'environments' => [
    'production' => [
        'supervisor-1' => [
            'tries' => 10,
        ],
    ],
],

Setting tries to 0 allows unlimited retries.

Job timeout

'environments' => [
    'production' => [
        'supervisor-1' => [
            'timeout' => 60,
        ],
    ],
],

Set timeout to a value a few seconds shorter than retry_after in config/queue.php. Also, the auto balance strategy may forcibly terminate jobs that run longer than this value.

Backoff (wait time before retry)

Specify the number of seconds to wait before retrying after an exception.

// Fixed value
'backoff' => 10,

// Progressive (exponential backoff)
'backoff' => [1, 5, 10],

Other worker options

In addition to tries, timeout, and backoff, each supervisor accepts options that control worker process behavior and when workers should automatically restart. Periodically restarting long-running processes is a good practice for preventing memory leaks.

'environments' => [
    'production' => [
        'supervisor-1' => [
            // ...
            'memory' => 128,
            'maxJobs' => 1000,
            'maxTime' => 3600,
            'sleep' => 3,
            'rest' => 0,
            'nice' => 0,
        ],
    ],
],

memory — the maximum memory (MB) a worker process can consume before restarting. Defaults to 128.
maxJobs — the number of jobs to process before restarting. 0 means unlimited. Defaults to 0.
maxTime — the number of seconds a worker can run before restarting. 0 means no time-based restart. Defaults to 0.
sleep — seconds to wait before polling for the next job when the queue is empty. Defaults to 3.
rest — seconds to pause between each job. Defaults to 0.
nice — the priority (“niceness”) of the worker process. Higher values mean lower priority. Defaults to 0.

Balance strategies

Horizon provides three worker balance strategies.

auto (default)

Automatically adjusts the number of workers based on queue load. Use minProcesses and maxProcesses to define the range.

'supervisor-1' => [
    'balance' => 'auto',
    'autoScalingStrategy' => 'time', // or 'size'
    'minProcesses' => 1,
    'maxProcesses' => 10,
    'balanceMaxShift' => 1,
    'balanceCooldown' => 3,
],

time — scales based on the estimated time to drain the queue.
size — scales based on the number of jobs in the queue.

Under the auto strategy, queue order does not indicate priority. If you need to enforce priority, use multiple supervisors.

simple

Uses a fixed number of workers and distributes them evenly across the configured queues.

'supervisor-1' => [
    'balance' => 'simple',
    'processes' => 10,
    'queue' => ['default', 'notifications'],
],

In the example above, five processes each are assigned to default and notifications.

false (no balancing)

Strictly prioritizes queues in the order listed. Behavior is similar to Laravel’s default queue system, but Horizon scales worker count based on backlog.

'supervisor-1' => [
    'balance' => false,
    'queue' => ['default', 'notifications'],
    'minProcesses' => 1,
    'maxProcesses' => 10,
],

Jobs on the default queue are always processed before jobs on notifications.

Dashboard authorization

Horizon’s dashboard is accessible at the /horizon route. In the local environment, anyone can access it by default, but in production you should restrict access via a gate. Edit the gate() method in app/Providers/HorizonServiceProvider.php.

use App\Models\User;
use Illuminate\Support\Facades\Gate;

protected function gate(): void
{
    Gate::define('viewHorizon', function (User $user) {
        return in_array($user->email, [
            '[email protected]',
        ]);
    });
}

If authentication isn’t required (for example, when you protect it via IP restriction), make the argument optional.

Gate::define('viewHorizon', function (User $user = null) {
    // When you restrict access by IP or similar
    return true;
});

Starting Horizon

Basic commands

# Start
php artisan horizon

# Pause / resume
php artisan horizon:pause
php artisan horizon:continue

# Pause / resume a specific supervisor
php artisan horizon:pause-supervisor supervisor-1
php artisan horizon:continue-supervisor supervisor-1

# Check status
php artisan horizon:status
php artisan horizon:supervisor-status supervisor-1

# Graceful shutdown
php artisan horizon:terminate

Local development: auto restart

Use the horizon:listen command to detect file changes and automatically restart Horizon.

npm install --save-dev chokidar
php artisan horizon:listen

# In Docker or Vagrant environments
php artisan horizon:listen --poll

Continuous operation with Supervisor

In production, use Supervisor to keep Horizon running.

Installing Supervisor

sudo apt-get install supervisor

Creating the config file

Create /etc/supervisor/conf.d/horizon.conf.

[program:horizon]
process_name=%(program_name)s
command=php /home/forge/example.com/artisan horizon
autostart=true
autorestart=true
user=forge
redirect_stderr=true
stdout_logfile=/home/forge/example.com/horizon.log
stopwaitsecs=3600

Set stopwaitsecs to a value larger than your longest-running job. Setting it too low will cause Supervisor to forcibly terminate jobs mid-flight.

Starting Supervisor

sudo supervisorctl reread
sudo supervisorctl update
sudo supervisorctl start horizon

On deploy

Restart Horizon on every code deploy so your changes take effect.

php artisan horizon:terminate

As long as Supervisor is configured with autostart=true / autorestart=true, it will restart Horizon automatically after termination.

Managing jobs

Silencing

You can silence jobs you don’t want shown in the “Completed Jobs” list on the dashboard by configuring config/horizon.php.

'silenced' => [
    App\Jobs\ProcessPodcast::class,
],

// Silence by tag
'silenced_tags' => [
    'notifications',
],

You can also implement the Silenced interface.

use Laravel\Horizon\Contracts\Silenced;

class ProcessPodcast implements ShouldQueue, Silenced
{
    use Queueable;
    // ...
}

Metrics and monitoring

Horizon’s metrics dashboard shows job and queue throughput and run time. Schedule regular snapshots to keep the data up to date.

// routes/console.php
use Illuminate\Support\Facades\Schedule;

Schedule::command('horizon:snapshot')->everyFiveMinutes();

The metrics.trim_snapshots option in config/horizon.php controls how many snapshots to keep for the metrics graphs. This setting limits by count rather than age, so the actual retention period depends on how often you run horizon:snapshot.

'metrics' => [
    'trim_snapshots' => [
        'job' => 24,
        'queue' => 24,
    ],
],

To delete all metrics data, run:

php artisan horizon:clear-metrics

Notifications on job failure

You can be notified when queue wait times grow long. Configure this in the boot() method of app/Providers/HorizonServiceProvider.php.

use Laravel\Horizon\Horizon;

public function boot(): void
{
    parent::boot();

    Horizon::routeMailNotificationsTo('[email protected]');
    Horizon::routeSlackNotificationsTo('slack-webhook-url', '#ops');
    Horizon::routeSmsNotificationsTo('15556667777');
}

Wait time thresholds

Configure the seconds of waiting that trigger notifications with the waits option in config/horizon.php.

'waits' => [
    'redis:critical' => 30,  // Notify after waiting 30 seconds or more
    'redis:default' => 60,
    'redis:batch' => 120,
],

Setting a value to 0 disables notifications for that queue.

Managing failed jobs

You can delete failed jobs by ID or UUID.

# Delete a specific failed job
php artisan horizon:forget 5

# Delete every failed job
php artisan horizon:forget --all

To clear every job on a queue, use:

# Clear the default queue
php artisan horizon:clear

# Clear a specific queue
php artisan horizon:clear --queue=emails

Upgrading

Always check the upgrade guide when upgrading Horizon to a major version.

Queues and jobs

The basics of Laravel queues — creating and dispatching jobs, batching, and handling failures.

Redis

Configuring and using the Redis backend that Horizon requires.

​What is Horizon?

​Installation

​Configuration

​Structure of config/horizon.php

​CSP nonce (Content Security Policy)

​Supervisors

​Default values

​Maintenance mode

​Maximum number of attempts

​Job timeout

​Backoff (wait time before retry)

​Other worker options

​Balance strategies

​Dashboard authorization

​Starting Horizon

​Basic commands

​Local development: auto restart

​Continuous operation with Supervisor

​Installing Supervisor

​Creating the config file

​Starting Supervisor

​On deploy

​Managing jobs

​Tags

​Silencing

​Metrics and monitoring

​Notifications on job failure

​Wait time thresholds

​Managing failed jobs

​Upgrading

​Related pages

Queues and jobs

Redis

What is Horizon?

Installation

Configuration

Structure of config/horizon.php

CSP nonce (Content Security Policy)

Supervisors

Default values

Maintenance mode

Maximum number of attempts

Job timeout

Backoff (wait time before retry)

Other worker options

Balance strategies

Dashboard authorization

Starting Horizon

Basic commands

Local development: auto restart

Continuous operation with Supervisor

Installing Supervisor

Creating the config file

Starting Supervisor

On deploy

Managing jobs

Tags

Silencing

Metrics and monitoring

Notifications on job failure

Wait time thresholds

Managing failed jobs

Upgrading

Related pages