Ringkasan Kasus: API Retry yang Mengulang Permintaan Secara Tak Terduga

Permintaan pelanggan jadi tidak konsisten karena layanan Retry API terus mengulang transaksi meski backend sudah memberikan respon sukses. Tujuan artikel ini adalah menjelaskan gejala awal, langkah observasi dengan log dan metrik, analisis akar masalah, dan perbaikan konkrit, sekaligus mengingatkan developer untuk menjaga fokus mental selama proses debugging.

Gejala dan Dampak Operasional

Tim melihat lonjakan antrian di queue background dan sejumlah resource downstream memberitahu ada duplikasi write. Metrik throughput API tetap stabil, tetapi waktu respons batch meningkat karena backend mengerjakan permintaan yang sudah selesai. Klien menerima beberapa callback hingga tiga kali, membuat idempotensi dan konsistensi data terganggu.

Observabilitas Awal

Observasi dimulai dari log gateway:

[2024-10-xxTxx:xx:xx] retry-api request_id=abc123 attempt=5 status=200 downstream_id=inv-987 duration=80ms

Log menunjukkan status 200 di setiap upaya tanpa error, tapi parameter attempt tetap meningkat. Metrik histogram latency queue memperlihatkan spike setiap kali retry dikirim ulang, sementara counter retry_attempt_total melonjol melebihi nilai normal.

Analisis Root Cause dan Alat Observasi

Menelusuri Log, Tracing, dan Metrik

Gabungan log retry dan tracing distribusi dari OpenTelemetry mengungkap pola: handler menerima callback_ack=true, namun event yang sama dikirim kembali karena worker tidak menghapus flag pending_retry. Analisis state store menyingkap bahwa worker hanya meng-set flag saat memulai eksekusi, tidak membersihkannya saat berhasil. Berikut query contoh untuk mengidentifikasi state bermasalah:

SELECT request_id, retry_state FROM retry_queue WHERE retry_state != 'idle' AND last_updated < now() - interval '10 seconds';

Log level debug menambahkan request_id, attempt, dan flag internal. Tanpa observasi tersebut, duplikasi terlihat seperti kegagalan downstream, bukan bug di service retry.

Root Cause: Flag State Tidak Direset Setelah Sukses

Implementasi awal hanya menghapus flag saat job mengalami exception. Ketika job selesai sukses, flag tetap bertahan (old code path terabaikan), sehingga scheduler menganggap job belum selesai dan menjadwalkan ulang secara agresif. Ini memicu loop retry walaupun backend sudah mengirim respons sukses.

Langkah Perbaikan Konkrit

Memperbaiki Lifecycle Flag dan Retry Policy

Perbaikan pertama adalah memastikan fungsi success handler membersihkan state:

def on_job_success(job_id):
    update_retry_state(job_id, 'idle')
    emit_metric('retry_state_cleared', 1)
    log.info('Retry state cleared', job_id=job_id)

Dengan begitu, scheduler tidak lagi menganggap job masih pending. Selain itu, perkuat retry policy agar ada cooldown dan limit eksplisit untuk mencegah penyusupan ke state utama.

Menambahkan Observasi untuk Idempotensi

Tambahkan log hash payload dan status sinkronisasi downstream. Hal ini membantu memastikan klaim “sukses” memang mencapai sistem target. Gunakan metric baru seperti idempotent_verification_failures agar bisa alert bila status retried tetap tidak sinkron.

Pemeriksaan dan Validasi Setelah Deploy

Uji end-to-end dengan job simulator yang merepresentasikan request asinkron. Pastikan simulasi melihat flag direset, tidak ada retry keempat, dan downstream menerima tepat satu data.

Menjaga Fokus dan Kesehatan Mental Saat Debugging

Selama incident, mudah tergoda membandingkan troubleshooting yang sedang terjadi dengan pengalaman rekan lain. Mengingat kalimat "I am that I am", kita diingatkan untuk tetap fokus pada masalah yang dihadapi, bukan membandingkan kecepatan progres dengan orang lain. Biarkan analisis berjalan dengan ritme logis, beri ruang istirahat singkat agar otak tetap jernih, dan ajak tim berdiskusi tanpa penilaian terhadap performa.

Checklist Verifikasi dan Dokumentasi Pasca-Inciden

  • ✅ Pastikan flag retry_reset di queue bertambah setiap kali job sukses dan tidak ada job dengan state pending lebih dari dua siklus.
  • ✅ Verifikasi bahwa downstream menerima satu callback untuk setiap request dari simulasi.
  • ✅ Periksa metrik retry_attempt_total dan pastikan kembali ke kurva normal dalam 30 menit setelah deploy.
  • ✅ Dokumentasikan timeline kejadian dengan log peristiwa, perubahan kode, hasil test, dan keputusan komunikasi.
  • ✅ Tulis post-mortem di repositori internal dengan penjelasan root cause, langkah preventif, dan pesan kesehatan mental yang mengingatkan tim untuk bekerja kolaboratif.

Dengan pendekatan observasi yang tepat, perbaikan state handling, dan perhatian kepada kesehatan mental, debug Retry API bisa selesai secara tuntas tanpa mengorbankan ketahanan tim.