Tutorial Monitoring Aplikasi Laravel, Queue, Scheduler, dan API

Ringkasan

Aplikasi Laravel yang terlihat normal di browser belum tentu sehat. Queue bisa macet, scheduler tidak jalan, atau API mulai lambat tanpa ada yang sadar. Tutorial ini membahas pengecekan dasar yang cukup realistis untuk server Linux: status aplikasi, worker queue, scheduler, log, dan endpoint API.

Prasyarat

Akses SSH ke server.
Folder proyek Laravel dan akses ke file .env.
PHP CLI, Composer, serta layanan queue seperti Redis atau database queue sudah tersedia.
Jika worker dijaga Supervisor atau systemd, Anda punya hak untuk melihat status servicenya.

Alur pemeriksaan membantu menentukan apakah masalah berasal dari koneksi, konfigurasi sharing, service, firewall, driver, atau kredensial.

Langkah 1: Siapkan endpoint kesehatan aplikasi

Untuk Laravel versi baru, endpoint /up biasanya sudah tersedia. Coba akses dari server agar pengecekan tidak tergantung DNS atau jaringan luar.

curl -i http://127.0.0.1/up

Targetnya respons HTTP 200. Endpoint ini sederhana, tetapi berguna sebagai alarm awal: web server, PHP, dan bootstrap Laravel setidaknya masih merespons. Bila aplikasi memakai domain HTTPS, cek juga dari luar server melalui URL publiknya.

Langkah 2: Pantau log Laravel

Log adalah tempat pertama yang saya buka saat ada laporan aplikasi terasa aneh. Jalankan perintah berikut dari folder proyek.

Gunakan checklist pengaturan agar setiap langkah penting diperiksa secara berurutan dan tidak ada konfigurasi yang terlewat.

tail -f storage/logs/laravel.log

Sambil membuka halaman aplikasi atau memanggil API, perhatikan error seperti koneksi database putus, Redis tidak tersedia, atau token API tidak valid. Jangan hanya melihat satu error terakhir; cari pola error yang berulang dalam beberapa menit terakhir.

Langkah 3: Periksa queue worker

Queue menangani pekerjaan yang tidak ideal dijalankan saat pengguna menunggu, misalnya kirim email, generate laporan, atau sinkronisasi data. Kalau worker mati, pekerjaan tetap masuk tetapi tidak pernah selesai.

Pastikan konfigurasi queue yang dipakai aplikasi:
```
grep QUEUE_CONNECTION .env
```
Untuk queue database, lihat pekerjaan yang tertunda:
```
php artisan tinker
DB::table('jobs')->count();
```
Jika memakai Supervisor, cek status worker:
```
sudo supervisorctl status
```
Untuk worker berbasis systemd, gunakan:
```
sudo systemctl status laravel-worker
```

Worker yang sehat biasanya berstatus RUNNING atau active (running). Jumlah job yang terus naik adalah tanda praktis bahwa worker lambat, berhenti, atau gagal memproses job tertentu.

Langkah 4: Cek job gagal dan retry seperlunya

Laravel menyimpan job gagal agar tidak hilang begitu saja. Lihat daftarnya dengan:

php artisan queue:failed

Baca dulu penyebabnya. Jangan langsung menjalankan ulang semua job, terutama jika job tersebut membuat invoice, mengirim notifikasi, atau memproses pembayaran. Setelah penyebabnya diperbaiki, satu job bisa dicoba ulang dengan:

php artisan queue:retry ID_JOB

Kalau worker sudah berjalan lama setelah deploy, restart worker dengan cara yang aman agar kode baru terbaca:

php artisan queue:restart

Langkah 5: Pastikan scheduler benar-benar dipanggil

Laravel scheduler tidak berjalan sendiri. Server harus memanggil schedule:run setiap menit lewat cron. Cek crontab user yang menjalankan aplikasi:

crontab -l

Pastikan ada entri seperti ini, dengan path proyek yang sesuai:

* * * * * cd /var/www/nama-aplikasi && php artisan schedule:run >> /dev/null 2>&1

Kenapa setiap menit? Laravel yang menentukan jadwal tugas mana yang perlu dieksekusi. Cron hanya bertugas membangunkan scheduler secara rutin.

Untuk melihat tugas yang terdaftar dan jadwal berikutnya:

php artisan schedule:list

Jika ingin memastikan tanpa menunggu cron, jalankan manual:

php artisan schedule:run

Tambahkan log singkat pada command terjadwal bila perlu. Ini lebih mudah diaudit daripada mengandalkan asumsi bahwa cron pasti jalan.

Langkah 6: Uji API dari server dan dari luar

API perlu dicek dari dua arah. Dari server, kita menguji aplikasi dan dependensi internal. Dari luar, kita ikut menguji DNS, SSL, firewall, reverse proxy, dan jaringan.

curl -sS -o /dev/null -w 'HTTP %{http_code} | %{time_total}s\n' https://domain-anda.tld/api/status

Sesuaikan endpoint dengan endpoint ringan yang tidak mengubah data. Catat dua hal: kode HTTP dan waktu respons. Respons 200 tetapi membutuhkan beberapa detik tetap perlu dicurigai, terutama bila sebelumnya cepat.

Cara cek hasil

Endpoint kesehatan mengembalikan HTTP 200.
Log tidak menunjukkan error berulang saat aplikasi dan API diakses.
Worker queue aktif dan jumlah job tertunda tidak terus menumpuk.
php artisan queue:failed tidak bertambah tanpa penanganan.
php artisan schedule:list menampilkan jadwal yang masuk akal, dan command terjadwal meninggalkan jejak log atau hasil kerja.
API publik merespons kode HTTP yang diharapkan dengan waktu respons stabil.

Kalau masih gagal

Queue tidak memproses job

Cek koneksi Redis atau database, lalu lihat log worker dan storage/logs/laravel.log. Pastikan nilai QUEUE_CONNECTION sama dengan layanan yang benar-benar tersedia. Setelah konfigurasi berubah, jalankan php artisan config:clear dan restart worker.

Scheduler tidak jalan

Pastikan cron dipasang pada user yang benar, path PHP benar, dan folder proyek bisa diakses user tersebut. Cek log cron sistem, biasanya melalui journal atau file log distribusi Linux. Kesalahan yang sering terjadi justru sederhana: cron memakai PHP versi berbeda dari PHP yang dipakai aplikasi.

API lambat atau 5xx

Mulai dari log Laravel dan log web server. Lalu cek database, Redis, serta koneksi ke layanan pihak ketiga. Jika endpoint memanggil layanan eksternal, pasang timeout yang masuk akal; jangan biarkan satu koneksi menggantung dan menahan seluruh request.

Tips operasional

Buat alert jika endpoint kesehatan gagal dua atau tiga kali berturut-turut. Satu kegagalan bisa saja gangguan singkat.
Pantau panjang antrean dan jumlah failed job, bukan hanya status proses worker.
Simpan log scheduler untuk tugas penting seperti backup, sinkronisasi stok, atau pengiriman laporan.
Setelah deploy, biasakan menjalankan migrasi yang diperlukan, membersihkan cache konfigurasi bila ada perubahan environment, lalu restart queue worker.
Pilih endpoint monitoring yang ringan dan tidak membocorkan detail internal aplikasi.

Penutup

Monitoring Laravel tidak harus langsung rumit. Yang penting, ada bukti bahwa aplikasi menjawab, worker memproses antrean, scheduler dipanggil, dan API bisa diakses dari jalur yang dipakai pengguna. Setelah pemeriksaan dasar ini konsisten, barulah masuk akal menambahkan dashboard seperti Laravel Horizon, uptime monitor, atau metrik Prometheus sesuai kebutuhan server.