Laravel Kuyruklarını Körlemesine Hata Ayıklamaktan Sıkıldım – Bu yüzden Özel Bir Dashboard Oluşturdum

Laravel kuyruklarını hatasız bir şekilde debug etmek, karanlıkta otomobil motorunu onarmaya benziyor — bir şeylerin yanlış olduğunu duyuyorsunuz, ama her adımda tahmin yapıyorsunuz. Loglara göz atarak saatler geçirdiyseniz, queue:work komutunu manuel olarak çalıştırdıysanız veya bir işin neden sessizce başarısız olduğunu anlamaya çalıştıysanız, bu acıyı biliyorsunuz. Bundan bıktım. Bu yüzden Redis’i yığına zorlamadan, gerçekten ihtiyaç duyduğunuz her şeyi açığa çıkaran hafif bir kontrol paneli oluşturdum.

Laravel Kuyruklarını Debug Etmenin Neden Her Zaman Acılı Olması

Laravel’in kuyruk sistemi gerçekten güçlü. database, Redis, SQS veya Beanstalkd sürücüleri kullanıp kullanmadığınız fark etmez, soyutlama temiz ve API şıktır. Sorun işlerin dağıtımında değil — işlerin ardından izlemekte.

Varsayılan deneyim şöyle görünür:

php artisan queue:work --tries=3

Bir iş başarısız olur. Laravel istisnayı storage/logs/laravel.log içinde bir yere kaydeder. Şanslıysanız, stack trace okunabilir. Şanssızsanız, o binlerce satır arasında doğru sınıf adını bulmak için grep kullanıyorsunuz, kahveniz soğumadan.

Telescope Açığı

Laravel Telescope bu sorun için resmi bir yanıt ve gerçekten kullanışlı — ama bazı sorunlarla geliyor. Ayrı bir veritabanı tablo migration’ı gerektiriyor, her isteğe ek yük ekliyor ve pratikte çoğu ekip bunu üretimde depolama alanı yüzünden devre dışı bırakıyor. 2026 yılına gelindiğinde, birçok ekip daha fazla gözlemlenebilirlik bütçesi ile daha sade işlemler yapıyor ve Telescope’un “her şeyi kaydet” yaklaşımı her durumda uygun değil.

Horizon, diğer yaygın öneri, ama sadece Redis ile çalışıyor. Küçük bir projeyi paylaşılan bir hostta çalıştırıyorsanız, maliyet farkındalığına sahip bir start-up iseniz veya veritabanı kuyruk sürücüsüne sahip bir miras uygulama üzerinde çalışıyorsanız, Horizon tam olarak bir seçenek değil.

Bu açık, beni özel bir şey inşa etmeye itti.

Karanlıkta Laravel Kuyruklarını Debug Etmekten Bıktım — Daha İyi Bir Geri Bildirim Döngüsü Kurdum

Temel içgörü basitti: bir kuyruğu debug etmek için gereken çoğu veritabanınızda zaten mevcut. Eğer database kuyruk sürücüsünü kullanıyorsanız, Laravel iş verilerini doğal olarak jobs ve failed_jobs tablolarında saklar. Eksik olan veri değil — bunun üstünde kullanışlı bir arayüz.

İşte Laravel’in size ücretsiz sağladığı şema:

-- jobs table
id, queue, payload, attempts, reserved_at, available_at, created_at

-- failed_jobs table
id, uuid, connection, queue, payload, exception, failed_at

failed_jobs içindeki exception sütunu, tam stack trace’i bir string olarak içerir. payload sütunu, iş verilerini (sınıf adı dahil) serileştirilmiş olarak saklar. İhtiyacınız olan her şey orada — sadece bunu tutarlı bir şekilde okuyacak bir şeye ihtiyacınız var.

Kontrol Panelini İnşa Etme: Temel Sorgu

Kontrol panelim, her sayfa yüklemesinde çalışacak iki sorgu ile başlıyor:

// Bekleyen ve çalışan işler
$active = DB::table('jobs')
    ->select(, , , , , )
    ->orderByDesc()
    ->limit()
    ->get()
    ->map(function ($job) {
        $payload = json_decode($job->payload, true);
        return [
            => $job->,
            => $job->,
            => $payload[] ?? ,
            => $job->,
            => $job->? : ,
            => $job->,
        ];
    });

// Başarısız işler
$failed = DB::table()
    ->select(, , , , , )
    ->orderByDesc()
    ->limit()
    ->get()
    ->map(function ($job) {
        $payload = json_decode($job->, true);
        $lines   = explode(", $job->);
        return [
            => $job->,
            => $job->,
            => $payload[] ?? ,
            => $lines[] ?? ,
            => $job->,
        ];
    });

Bu sorgu, iş sınıfı adını, kuyruk adını, mevcut durumu, deneme sayısını ve istisnanın ilk satırını verir — 90% zamanında gerçekten işe yarayan kısım.

Livewire Bileşenine Bağlama

2026 yılında, Livewire v3, tam bir SPA çerçevesine başvurmaksızın Laravel’deki reaktif kontrol panelleri için mantıklı bir seçim. Basit bir polling bileşeni, kontrol panelini her birkaç saniyede bir günceller:

namespace App\Livewire;

use Illuminate\Support\Facades\DB;
use Livewire\Component;

class QueueDashboard extends Component
{
    public $activeJobs  = [];
    public $failedJobs  = [];
    public $autoRefresh = true;

    #[\Livewire\Attributes\Poll('3s')]
    public function refreshJobs(): void
    {
        $this->activeJobs = $this->fetchActiveJobs();
        $this->failedJobs = $this->fetchFailedJobs();
    }

    public function retryJob(string $uuid): void
    {
        \Artisan::call(, [=> [$uuid]]);
        $this->refreshJobs();
    }

    public function render()
    {
        $this->refreshJobs();
        return view();
    }

    // ... yukarıdaki fetch yöntemleri
}

#[Poll('3s']} niteliği, JavaScript olmadan otomatik yenilemeyi yönetir. Her başarısız iş için bir yeniden deneme düğmesi ekleyerek queue:retry all komutunu tek tıklama ile değiştirdiniz.

Kontrol Panelini Üretimde Koruma

Bu, çoğu eğitim makalesinin atladığı bir kısım ve takımların yanıldığı yer. Kuyruk kontrol paneliniz, iş sınıfı adlarını, kuyruk adlarını ve istisna mesajlarını açığa çıkarır — muhtemelen serileştirilmiş modellerden gelen hassas verileri de içerir. Bunu kenara bırakmayın.

Rotayı bir middleware gate içinde sarın:

// routes/web.php
Route::middleware([, ])
    ->prefix()
    ->group(function () {
        Route::get(, QueueDashboard::)->name();
    });

Ve gate’i AppServiceProvider içerisinde tanımlayın:

Gate::define(, function ($user) {
    return in_array($user->, config(, []));
});

İzin verilen e-postaları .env dosyanıza kaydedin ve üretim güvenliğinde, rol-temelli bir kontrol paneline sahip olursunuz. Ek bir pakete ihtiyacınız yok.

Karanlıkta Laravel Kuyruklarını Debug Etmekten Bıktım — İşte Gerçekten Değişenler

Bu kontrol panelini birkaç üretim projesi boyunca birkaç ay boyunca çalıştırdıktan sonra, somut iyileştirmeleri ölçmek mümkündü.

Başarısız bir işi debug etme süresi yaklaşık 25 dakikadan 2 dakikanın altına düştü. Daha önceki iş akışı: bir şeylerin ters gittiğini fark etmek → sunucuya SSH ile bağlanmak → logları takip etmek → iş sınıfını bulmak → hatayı bulmak → zaman damgaları ile ilişkilendirmek. Şimdi ise: kontrol panelini açın → kırmızı satıra göz atın → istisnayı okuyun → yeniden dene veya kodu düzeltin. Hepsi bu kadar.

Sessiz hatalar görünür hale geldi. max_tries sayısını aşan ve failed_jobs tablosundan temizlenecek şekilde yapılandırılmış olan işler — yanlış yapılandırılmış bir --max-time veya çalışmayan bir cron nedeniyle — aktif iş sayısındaki ani düşüşler olarak belirmeye başladı. Kontrol paneli, işlerin yokluğunu, varlığı kadar görünür hale getirdi. Bu, log dosyalarının takibinden alamayacağınız bir sinyal.

Kuyruk derinliği bir metrik haline geldi, sürpriz olmadı. Bekleyen iş sayısının bir trafik artışı sırasında yükselmesini izlemek gerçekten işe yarar. Bu, işçileri proaktif olarak ölçeklendirmek ve neden maillerin gönderilmediğinin nedenini reaktif olarak debug etmenin farkıdır.

Ne Zaman Hala Horizon veya Pulse Kullanmalısınız?

Bu kontrol paneli, ölçekli Redis destekli üretim sistemleri için bir Horizon yerine geçmez. Günde yüz binlerce işi işliyorsanız, Laravel Horizon’un metriklerini, verimlilik grafiklerini ve denetçi yönetimini istemelisiniz. Eğer zaten Laravel 11+ üzerindeyseniz ve daha derin uygulama gözlemlenebilirliği istiyorsanız, Laravel Pulse kuyruk metriklerini, veritabanı, önbellek ve HTTP içgörüleri ile birleşik bir görünümde sunar. Bunlar gerçek ölçek için gerçek araçlardır — bunu küçümsemiyorum.

Ancak veritabanı sürücüsünde, bir şeyleri prototipliyorsanız veya tam sahiplik ve sıfır ek bağımlılık istediğiniz kısıtlı bir ortamda çalışıyorsanız uygunlar mı? Hayır. Bu yaklaşım, tam da burada devreye giriyor.

Bugün Gönderilebilecek Özler

Bunu bir öğleden sonra inşa edin — temeller basit:

1. İki temel sorguyla başlayın — jobs ve failed_jobs — ihtiyacınız olan her şey zaten orada
2. Gerçek zamanlı güncellemeler için Livewire v3 Poll bileşenini kullanın — JavaScript karmaşası olmadan
3. Rotayı koruyun — auth middleware ve bir adlandırılmış Gate ile — üretimde bunu atlamayın
4. İlk istisna satırını açığa çıkarın — bu, anlık bir bakışta okunabilir ve derin izleme için bağlantılar içerir
5. Her iş için bir yeniden deneme düğmesi ekleyin — Artisan::call('queue:retry', ['id'=>[$uuid]]) ile — bu, önemli ölçüde zaman kazandırır

Tüm bu şeyler 200 satırdan az PHP ve bir Blade şablonuyla. Karanlıkta uçmaya devam etmenin bir sebebi yok.

Bu makale ilk olarak qcode.in‘de yayımlanmıştır.