Job yang masuk ke sistem queue tetapi tidak pernah diproses biasanya tersendat di salah satu batas alur: producer tidak mengirim ke tujuan yang benar, worker tidak berlangganan ke queue tersebut, worker tidak aktif, atau pesan tertahan setelah gagal diproses. Mulailah dengan memastikan ke mana pesan dikirim dan queue mana yang benar-benar dibaca worker, lalu cocokkan temuan itu dengan metrik dan log.

Pendekatan ini mirip mendiagnosis komponen React yang ada di kode tetapi tidak pernah dirender: keberadaan artefak tidak membuktikan bahwa artefak tersebut dijalankan. Dalam sistem queue, pesan yang tampak di dashboard belum membuktikan bahwa worker menerima atau mengklaimnya.

Petakan alur job dari producer ke worker

Gambarkan alur aktual sebelum mengubah konfigurasi. Secara umum, producer membuat job dan mengirimkannya ke broker atau penyimpanan queue; sistem merutekan pesan ke queue; worker berlangganan dan mengambil pesan; lalu handler memprosesnya serta mengakui keberhasilan atau kegagalan.

  1. Producer: Pastikan jalur kode yang membuat job benar-benar dijalankan dan pengiriman berhasil.
  2. Tujuan pesan: Catat nama queue, exchange atau kanal perutean, routing key, serta koneksi atau lingkungan yang digunakan.
  3. Worker: Pastikan worker berlangganan ke tujuan yang sama dan menjalankan handler yang sesuai.
  4. Hasil pemrosesan: Periksa apakah pesan diakui, dicoba ulang, ditunda, atau dipindahkan ke dead-letter queue.

Periksa setiap batas secara terpisah. Jika producer dan worker memakai konfigurasi berbeda—misalnya lingkungan, kredensial, namespace, atau nama queue—keduanya mungkin sehat tetapi tidak pernah bertemu.

Periksa producer, nama queue, dan routing

Pastikan producer mengirim job

Telusuri titik pemanggilan producer dan periksa hasil pengiriman, log, serta penanganan error. Jangan menyimpulkan job berhasil terkirim hanya karena fungsi pembuat job terpanggil. Dalam pola transactional outbox, misalnya, job mungkin baru diterbitkan setelah transaksi lain berhasil atau setelah proses penerbitan outbox berjalan.

Bandingkan identitas pesan atau ID job pada log aplikasi dengan pesan yang terlihat di broker. Pastikan producer mengarah ke broker dan lingkungan yang benar; kesalahan konfigurasi dapat membuat job masuk ke instance pengembangan, region lain, atau proyek lain.

Cocokkan queue dan routing key

Nama queue, routing key, exchange, topic, atau subscription memiliki peran berbeda bergantung pada teknologi yang digunakan. Periksa konfigurasi producer dan worker, lalu cocokkan nilai serta aturan binding di broker. Kesalahan ejaan atau perbedaan sufiks lingkungan sudah cukup untuk membuat worker tidak menerima pesan.

Pada broker yang merutekan pesan melalui exchange, producer dapat berhasil menerbitkan pesan tanpa ada queue yang cocok menerima pesan tersebut. Periksa hasil routing dan konfigurasi binding, bukan hanya status sukses dari operasi publish. Pada sistem yang menggunakan nama queue secara langsung, pastikan worker berlangganan ke nama yang sama persis dengan tujuan producer.

Periksa konfigurasi subscription dan kondisi worker

Pastikan worker benar-benar berlangganan

Verifikasi queue atau subscription yang dipantau worker saat runtime. Bandingkan konfigurasi efektif—setelah variabel lingkungan, file konfigurasi, dan argumen proses diterapkan—dengan konfigurasi producer. Perhatikan juga filter, consumer group, namespace, kredensial, dan izin baca yang dapat membatasi pesan yang terlihat.

Periksa jumlah consumer aktif di broker dan log saat worker mulai. Proses yang hidup belum tentu menjadi consumer: worker dapat gagal mendaftar, terhubung ke broker yang berbeda, atau berhenti sebelum berlangganan. Cari error autentikasi, izin, koneksi, resolusi nama, serta kegagalan inisialisasi handler.

Bedakan worker tidak aktif dari worker macet

Periksa status proses atau container, jumlah replika, restart berulang, penggunaan CPU dan memori, serta heartbeat jika sistem menyediakannya. Jika consumer aktif tetapi jumlah pesan yang sedang diproses terus bertambah tanpa penyelesaian, handler mungkin lambat, macet, atau menunggu dependensi eksternal. Jika tidak ada consumer aktif, fokus pada deployment, perintah start, konfigurasi subscription, dan konektivitas.

Gunakan metrik, log, dan status pesan

Gabungkan beberapa sinyal; satu metrik saja jarang cukup untuk menentukan penyebab. Pantau setidaknya:

  • Kedalaman queue: Jumlah pesan yang menunggu. Kenaikan terus-menerus menunjukkan laju masuk melebihi laju pemrosesan atau tidak ada consumer yang mengambil pesan.
  • Usia pesan tertua: Waktu tunggu pesan terlama. Nilai yang meningkat membantu membedakan backlog baru dari pesan lama yang tidak pernah tersentuh.
  • Jumlah pesan yang sedang diproses: Jika tersedia, tren ini membantu menemukan consumer yang mengambil pesan tetapi lambat menyelesaikannya.
  • Jumlah percobaan ulang dan dead-letter: Kenaikan dapat menunjukkan kegagalan handler, kebijakan retry, atau pesan yang tidak dapat diproses.
  • Jumlah dan status consumer: Pastikan jumlah consumer aktif sesuai dengan deployment yang diharapkan.

Cocokkan rentang waktu metrik dengan log producer, broker, worker, dan layanan dependensi. Gunakan ID job atau correlation ID yang sama untuk menelusuri satu pesan. Log perlu membedakan job dibuat, diterbitkan, diterima worker, mulai diproses, dan selesai atau gagal. Hindari mencatat payload sensitif; gunakan ID dan metadata yang aman.

Perhatikan perbedaan antara pesan yang menunggu, pesan yang sedang diproses, dan pesan yang sudah dipindahkan ke dead-letter queue. Pesan yang tidak terlihat pada queue utama mungkin sudah dipindahkan oleh kebijakan retry atau dead-letter, bukan hilang.

Diagnosis berdasarkan gejala dan lakukan perbaikan

  • Kedalaman queue dan usia pesan naik, consumer nol: Aktifkan atau pulihkan worker, perbaiki perintah start atau konfigurasi subscription, lalu pastikan worker mendaftar pada queue yang benar.
  • Producer mencatat pengiriman, tetapi queue tetap kosong: Periksa tujuan broker, aturan routing dan binding, filter, serta apakah pesan ditolak atau tidak memiliki tujuan yang cocok.
  • Queue utama kosong, dead-letter queue bertambah: Periksa alasan kegagalan, kebijakan retry, batas percobaan, dan perubahan kode handler. Perbaiki penyebab sebelum memutar ulang pesan.
  • Consumer aktif dan pesan sedang diproses bertambah: Periksa log handler, dependensi yang lambat, timeout, konkurensi, dan mekanisme pengakuan pesan. Jangan menaikkan jumlah worker sebelum memastikan kapasitas dependensi dan keamanan pemrosesan ulang.
  • Hanya job dari satu jenis yang tertahan: Cocokkan queue atau routing key khusus job itu, versi konfigurasi worker, dan pendaftaran handler.

Setelah penyebab diperbaiki, proses ulang pesan secara terkendali jika diperlukan. Pastikan handler aman terhadap pemrosesan ulang atau gunakan mekanisme deduplikasi yang sesuai sebelum memutar ulang pesan; retry dapat mengulang efek samping yang sudah terjadi. Hindari menghapus queue atau mengosongkan dead-letter queue sebagai langkah pertama karena tindakan itu dapat menghilangkan data yang diperlukan untuk diagnosis atau pemulihan.

Cegah regresi

  • Uji alur end-to-end: terbitkan satu job ke lingkungan uji, pastikan worker menerimanya, dan verifikasi hasil akhirnya.
  • Validasi konfigurasi queue, routing, dan subscription saat aplikasi atau worker dimulai agar ketidaksesuaian cepat terlihat.
  • Buat peringatan untuk usia pesan tertua dan pertumbuhan backlog, bukan hanya jumlah pesan.
  • Catat tahapan siklus hidup job dengan ID yang dapat dikorelasikan di producer dan worker.
  • Tinjau kebijakan retry dan dead-letter, serta sediakan prosedur aman untuk inspeksi dan pemutaran ulang.
  • Pastikan deployment worker memiliki pemeriksaan kesehatan yang menunjukkan kesiapan berlangganan, bukan sekadar proses berjalan.

Diagnosis paling cepat datang dari bukti pada setiap batas: producer membuat dan mengirim job, routing menempatkannya pada tujuan yang tepat, worker berlangganan pada tujuan itu, dan handler menyelesaikan pesan. Metrik kedalaman serta usia pesan tertua menunjukkan di mana alur berhenti; log dan status dead-letter membantu menjelaskan alasannya.