Laravel Horizon and Telescope: Queue Monitoring & Debugging

In modern web applications, handling background tasks efficiently is crucial for performance and user experience. Laravel's queue system allows you to defer time-consuming tasks like sending emails, processing images, or generating reports. However, as your application grows, monitoring queues and debugging issues becomes a challenge. This is where Laravel Horizon and Telescope come in. Horizon provides a beautiful dashboard to monitor your queues, view metrics, and manage failed jobs. Telescope offers deep debugging capabilities, capturing requests, exceptions, queries, and more. Together, they form a powerful toolkit for maintaining and troubleshooting Laravel applications in production. In this tutorial, you'll learn how to install, configure, and use both tools effectively, with real-world examples and best practices.

Installing and Configuring Horizon

Horizon requires Redis and the predis or phpredis driver. Install via Composer: composer require laravel/horizon. Publish assets and configuration: php artisan vendor:publish --provider="Laravel\Horizon\HorizonServiceProvider". Configure .env with QUEUE_CONNECTION=redis and REDIS_HOST=.... The config/horizon.php file allows you to define environments, balance strategies, and supervisor settings. For production, set 'environments' => ['production' => ['supervisor-1' => ['connection' => 'redis', 'queue' => ['default'], 'balance' => 'auto', 'processes' => 3, 'tries' => 3]]]. Use php artisan horizon to start the dashboard. Secure it with authentication middleware in HorizonServiceProvider::gate().

<?php

return [
    'environments' => [
        'production' => [
            'supervisor-1' => [
                'connection' => 'redis',
                'queue' => ['default'],
                'balance' => 'auto',
                'processes' => 3,
                'tries' => 3,
            ],
        ],
        'local' => [
            'supervisor-1' => [
                'connection' => 'redis',
                'queue' => ['default'],
                'balance' => 'simple',
                'processes' => 1,
                'tries' => 1,
            ],
        ],
    ],
];

Monitoring Queues with Horizon Dashboard

Once Horizon is running, access the dashboard at /horizon. It shows real-time metrics: jobs processed per minute, queue status, failed jobs, and worker count. You can pause, resume, or terminate queues. The 'Failed Jobs' tab lists all failed jobs with their exception messages and stack traces. You can retry or delete them. Horizon also provides a 'Metrics' section with charts for throughput and runtime. Use tags to group jobs by type (e.g., SendEmailJob). The dashboard is invaluable for spotting bottlenecks and ensuring workers are healthy.

<?php

namespace App\Jobs;

use Illuminate\Bus\Queueable;
use Illuminate\Contracts\Queue\ShouldQueue;
use Illuminate\Foundation\Bus\Dispatchable;
use Illuminate\Queue\InteractsWithQueue;
use Illuminate\Queue\SerializesModels;

class SendEmailJob implements ShouldQueue
{
    use Dispatchable, InteractsWithQueue, Queueable, SerializesModels;

    public $user;

    public function __construct($user)
    {
        $this->user = $user;
    }

    public function handle()
    {
        // Send email logic
    }

    public function tags()
    {
        return ['send_email', 'user:'.$this->user->id];
    }
}

Installing and Configuring Telescope

Telescope is a debugging companion that captures requests, exceptions, database queries, and more. Install via composer require laravel/telescope. Then run php artisan telescope:install and php artisan migrate. Publish config: php artisan vendor:publish --provider="Laravel\Telescope\TelescopeServiceProvider". In .env, set TELESCOPE_ENABLED=true for local and optionally for production. Configure watchers in config/telescope.php to enable/disable specific data collection. For production, limit data retention with 'limit' => 1000 and use the 'storage' driver (database by default). Secure the dashboard similarly to Horizon.

<?php

return [
    'watchers' => [
        Laravel\Telescope\Watchers\RequestWatcher::class => [
            'enabled' => env('TELESCOPE_ENABLED', true),
            'size_limit' => 100,
        ],
        Laravel\Telescope\Watchers\ExceptionWatcher::class => [
            'enabled' => true,
        ],
        Laravel\Telescope\Watchers\QueryWatcher::class => [
            'enabled' => env('TELESCOPE_ENABLED', true),
            'slow' => 100,
        ],
        // ... other watchers
    ],
    'limit' => 1000,
];

Debugging with Telescope: Requests, Queries, and Exceptions

Telescope's dashboard at /telescope shows a timeline of requests. Each entry includes method, URI, duration, status code, and memory usage. Click to see headers, input, session, and response. The 'Queries' tab lists all database queries with bindings and execution time, helping identify N+1 problems. The 'Exceptions' tab captures all thrown exceptions with stack traces and request context. You can filter by type or status. Telescope also logs mail, notifications, cache hits/misses, and scheduled tasks. Use the 'Search' feature to find specific entries by tag or content.

<?php

namespace App\Http\Controllers;

use App\Models\User;
use Illuminate\Http\Request;

class UserController extends Controller
{
    public function index()
    {
        // N+1 problem example
        $users = User::all();
        foreach ($users as $user) {
            echo $user->profile->bio; // Each access triggers a query
        }
    }
}

Integrating Horizon and Telescope with Supervisor

In production, both Horizon and Telescope need to run as daemons. Use Supervisor to manage Horizon processes. Create a configuration file at /etc/supervisor/conf.d/horizon.conf with command php artisan horizon. For Telescope, no daemon is needed; it records data passively. However, ensure the queue worker (Horizon) is running to process jobs. Supervisor will restart Horizon if it crashes. Monitor Horizon's log file for errors. Telescope's data is stored in the database; schedule pruning with telescope:prune.

[program:horizon]
process_name=%(program_name)s
command=php /path/to/artisan horizon
autostart=true
startsecs=5
startretries=10
user=forge
redirect_stderr=true
stdout_logfile=/var/log/horizon.log
stopwaitsecs=3600

Advanced Features: Tags, Watchers, and Custom Data

Horizon allows tagging jobs for filtering. Telescope supports custom watchers and recording custom events. You can add tags to Telescope entries using Telescope::tag() in service providers. Create custom watchers by extending Laravel\Telescope\Watchers\Watcher. For example, a watcher to log external API calls. Use Telescope::record() to manually log entries. This is useful for monitoring third-party service interactions. Both tools support environment-specific configurations via config/horizon.php and config/telescope.php.

<?php

namespace App\Providers;

use Laravel\Telescope\Telescope;
use Illuminate\Support\Facades\Gate;
use Laravel\Telescope\IncomingEntry;
use Laravel\Telescope\TelescopeApplicationServiceProvider;

class TelescopeServiceProvider extends TelescopeApplicationServiceProvider
{
    protected function gate()
    {
        Gate::define('viewTelescope', function ($user) {
            return $user->isAdmin();
        });
    }

    protected function registerTags()
    {
        Telescope::tag(function (IncomingEntry $entry) {
            if ($entry->type === 'request') {
                return ['status:'.$entry->content['response_status']];
            }
            return [];
        });
    }
}