Belajar NATS - Troubleshooting

#Pendahuluan

Tidak ada sistem yang tidak pernah bermasalah. Episode 19 ini mempersenjatai kalian menghadapi masalah-masalah paling umum di NATS: consumer yang lambat, redelivery yang tak berujung, storage penuh, kehilangan quorum, dan tabrakan subject.

Untuk setiap masalah, kita akan bahas gejalanya, penyebabnya, dan cara memadamkannya dengan perangkat diagnostik yang sudah kalian kenal. Mari mulai dari masalah yang paling sering terjadi.

#Slow Consumer dan Backpressure

#Gejala dan Penyebab

Slow consumer terjadi ketika consumer tidak mampu mengejar kecepatan publisher. Gejalanya: nats consumer report menunjukkan pending yang terus naik, dan pesan di stream menumpuk.

nats consumer report ORDERS
nats server check consumer

nats consumer report ORDERS menampilkan pending per consumer. nats server check consumer memverifikasi kesehatan seluruh consumer dalam satu langkah.

#Solusi

• Tambah worker pada queue group atau pull consumer yang sama.
• Naikkan jumlah pull consumer agar beban terbagi.
• Perlambat publisher dengan batching yang lebih kecil.
• Periksa proses worker: mungkin ada blocking call atau leak.

#Redelivery Tak Berujung

#Lingkaran Kirim Ulang

Redelivery tak berujung terjadi ketika worker tidak pernah berhasil mengack, padahal max_deliver tidak tercapai — biasanya karena ack_wait terlalu pendek untuk pekerjaan yang lama, atau handler memakai ack yang salah.

nats consumer report ORDERS

nats consumer report ORDERS menunjukkan kolom Redeliveries. Angka yang tinggi dan naik terus berarti pesan gagal diproses berulang.

#Solusi

• Perpanjang ack_wait agar sesuai durasi pemrosesan normal.
• Periksa kode handler: pastikan msg.Ack() dipanggil di jalur sukses.
• Naikkan max_deliver hanya jika benar-benar perlu, lalu kirim ke dead letter.

nats consumer edit ORDERS WORKER --ack-wait 5m --max-deliver 5

--ack-wait 5m memberi waktu proses lebih panjang. Aturan praktis: ack_wait harus lebih besar dari waktu proses terburuk yang masih wajar.

#Storage Penuh karena max_bytes

#Disk yang Terus Tumbuh

Stream tanpa batas ukuran akan terus membesar sampai memenuhi disk. Gejalanya: server crash, publish gagal, dan log menampilkan error storage.

nats stream report
df -h

nats stream report menunjukkan penggunaan storage per stream; df -h memeriksa ruang disk server. Jika disk hampir penuh, tindakan harus segera.

#Solusi

• Tetapkan max_bytes pada setiap stream.
• Perpendek max_age untuk data yang tidak perlu lama.
• Hapus stream atau consumer yang tidak terpakai.

nats stream edit ORDERS --max-bytes 10G --max-age 30d

--max-bytes 10G --max-age 30d membatasi stream hingga 10 GB atau 30 hari, mana yang tercapai lebih dulu. Dua batasan ini mencegah disk meledak.

#Kehilangan Quorum

#Cluster yang Gagal Berkonsensus

Quorum loss terjadi ketika jumlah node sehat kurang dari mayoritas. Gejalanya: stream replicas 3 menampilkan health menurun, publish ke stream gagal, dan leader tidak terpilih.

nats stream report
nats server check cluster

nats server check cluster memverifikasi kesehatan cluster dan quorum. Jika cluster kehilangan quorum, stream tidak bisa menerima tulis.

#Solusi

• Kembalikan node yang mati secepat mungkin.
• Pastikan jumlah node ganjil untuk toleransi maksimal.
• Jangan restart semua node bersamaan.
• Periksa konektivitas jaringan antar node pada port 6222.

#Subject Collision

#Dua Stream Berebut Subject

Subject collision terjadi ketika dua stream menangkap subject yang sama dalam satu akun. NATS menolak pembuatan stream kedua dengan error subject already covered by another stream.

nats stream report
nats stream info ORDERS

nats stream info ORDERS menunjukkan daftar subject yang ditangkap. Membandingkan daftar subject antar stream mengungkap tumpang tindih.

#Solusi

• Rancang skema subject dengan prefix unik per domain.
• Gunakan wildcard dengan hati-hati — orders.> dan orders.* bisa bertabrakan.
• Jika collision tak terhindarkan, gabungkan subject dalam satu stream.

#Perangkat Diagnostik Lengkap

#Alur Investigasi yang Terstruktur

Saat ada masalah, jalankan langkah berikut secara berurutan:

nats server check
nats stream report
nats consumer report
nats server check ping

nats server check ping memeriksa latensi server. Tambahkan log debug bila perlu:

nats-server -D

Flag -D mengaktifkan log debug. Nyalakan hanya saat investigasi, lalu matikan — log debug penuh di produksi menurunkan performa seperti yang dibahas di episode 18.

#Penutup

Episode 19 melatih kalian memadamkan api: slow consumer yang diatasi dengan menambah worker dan pull consumer, redelivery tak berujung yang diperbaiki lewat ack_wait yang tepat, storage penuh yang dicegah dengan batasan max_bytes dan max_age, quorum loss yang ditangani dengan menjaga jumlah node ganjil, serta subject collision yang dihindari dengan skema penamaan yang disiplin.

Inti yang harus dibawa pulang:

• Pending naik terus adalah tanda slow consumer; tambah worker atau perbaiki handler.
• Redelivery tinggi biasanya berarti ack_wait terlalu pendek.
• Setiap stream wajib punya max_bytes dan max_age agar disk aman.
• Quorum loss membutuhkan jumlah node sehat lebih dari mayoritas.
• Subject collision dicegah dengan skema penamaan dan wildcard yang hati-hati.
• nats server check dan kedua report adalah senjata diagnostik utama.

Di episode 20 selanjutnya kita akan membahas fitur stabil terbaru v2.14 — evolusi rilis dari v2.10 ke v2.12 lalu v2.14, panduan upgrade dan backward compatibility, serta fitur 2026: high-throughput publish, server-side message scheduling, perbaikan sourcing dan mirroring, dan metrik in_client serta out_client. Pengetahuan kalian akan diperbarui ke rilis terkini.