Replayable Worker Queue adalah pendekatan untuk membuat eksekusi job di sistem queue bisa dilacak, diputar ulang, diuji dengan cabang alternatif, dan bila perlu dikembalikan ke state sebelumnya tanpa menebak-nebak apa yang terjadi di produksi. Ini berguna saat Anda menghadapi job yang gagal intermiten, retry yang malah memperburuk state, lock yang kedaluwarsa, cache yang berbeda dari database, atau race condition antar worker.

Inti desainnya bukan sekadar menambah log. Anda perlu runtime trace yang merekam keputusan penting, perubahan state yang relevan, dependensi eksternal, serta batas aman kapan sebuah replay boleh menyentuh sistem nyata. Gagasan ini sejalan dengan pendekatan trace yang reversible seperti yang menginspirasi beberapa runtime modern: eksekusi tidak hanya diamati, tetapi dibuat cukup deterministik untuk dianalisis ulang.

Mengapa worker queue sulit di-debug

Masalah di worker queue jarang muncul sebagai satu exception yang jelas. Yang lebih sering terjadi adalah kombinasi faktor:

  • Job gagal intermiten: timeout jaringan, dependensi eksternal lambat, payload tidak konsisten, atau state data berubah di tengah proses.
  • Retry mengubah state: job yang tidak idempoten mengirim email dua kali, memotong stok dua kali, atau membuat duplikasi row.
  • Lock kedaluwarsa: satu worker masih jalan, lock sudah habis, worker lain mengambil job yang sama.
  • Cache tidak konsisten: worker membaca cache lama, lalu menulis hasil yang bertentangan dengan data sumber.
  • Race condition antar worker: dua job yang tampak terpisah ternyata memodifikasi entitas yang sama dengan urutan yang tidak stabil.

Log biasa sering tidak cukup karena hanya menunjukkan gejala akhir. Untuk benar-benar memahami akar masalah, Anda perlu tahu urutan kejadian, state input di setiap langkah, dan efek samping apa yang sudah terjadi.

Target arsitektur: traceable, replayable, forkable, reversible

Worker queue yang mudah di-debug biasanya punya empat sifat berikut:

  • Traceable: setiap job memiliki jejak eksekusi terstruktur, bukan hanya teks log.
  • Replayable: job bisa dijalankan ulang dari input dan trace yang sama untuk melihat apakah hasilnya konsisten.
  • Forkable: Anda bisa membuat cabang eksekusi dari titik tertentu untuk menguji perbaikan, misalnya mengganti lock strategy atau memperbaiki validasi payload.
  • Reversible: perubahan state yang dikelola internal dapat dikembalikan atau disimulasikan rollback-nya dalam lingkungan aman.

Tujuannya bukan membuat semua side effect bisa dibatalkan sepenuhnya. Itu sering tidak realistis, terutama untuk email, webhook, atau pembayaran. Yang realistis adalah memisahkan state internal yang bisa dikontrol dari efek eksternal yang harus diisolasi.

Arsitektur inti event trace

1. Pisahkan lifecycle job dan domain events

Simpan dua jenis event:

  • Queue lifecycle events: job diterima, mulai dieksekusi, lock diambil, lock diperpanjang, retry dijadwalkan, selesai, gagal, dipindahkan ke dead-letter queue.
  • Domain execution events: payload divalidasi, order dimuat, stok dicek, cache dibaca, API eksternal dipanggil, status order diubah.

Pemisahan ini penting karena masalah operasional dan masalah logika bisnis sering bercampur. Dengan struktur event yang jelas, Anda bisa menjawab pertanyaan seperti: job gagal karena bug bisnis, atau karena lock hilang dan dua worker menulis state bersamaan?

2. Gunakan format trace yang terstruktur

Setiap event trace sebaiknya memiliki field minimum berikut:

  • trace_id: identitas seluruh eksekusi.
  • job_id: identitas job queue.
  • attempt: nomor percobaan.
  • step: nama langkah logis, misalnya load_order atau charge_payment.
  • timestamp: waktu kejadian.
  • worker_id: worker yang menjalankan.
  • resource_version: versi row, revision, atau etag jika ada.
  • input_ref dan output_ref: referensi ke payload atau snapshot besar agar event tetap ringan.
  • side_effect: apakah langkah ini melakukan I/O nyata.
  • status: success, fail, skipped, compensated.

Hindari menyimpan semua data mentah ke setiap event. Lebih baik simpan referensi ke object storage atau snapshot store agar biaya penyimpanan tetap terkendali.

3. Rekam keputusan, bukan hanya hasil

Trace yang berguna untuk replay harus mencatat mengapa sistem memilih suatu cabang. Contoh:

  • Cache hit atau miss.
  • Nilai lock owner saat konflik.
  • Alasan retry: timeout, dependency unavailable, optimistic conflict.
  • Kondisi validasi yang menyebabkan job berhenti.

Jika trace hanya berisi “API gagal”, Anda tetap harus menebak-nebak. Jika trace mencatat timeout threshold, request id, dan apakah fallback dijalankan, replay jadi jauh lebih berguna.

Snapshot dan copy-on-write untuk state yang bisa direplay

Kapan perlu snapshot

Replay yang akurat membutuhkan state yang mendekati keadaan saat insiden terjadi. Ada dua pendekatan umum:

  • Snapshot penuh: salin state entitas yang relevan sebelum atau sesudah langkah penting.
  • Delta/change-set: simpan perubahan per langkah dan bangun ulang state dari rangkaian perubahan.

Untuk sistem queue backend, pendekatan praktis biasanya campuran: snapshot periodik untuk entitas penting, lalu delta untuk perubahan antar snapshot.

Copy-on-write lebih realistis daripada clone penuh

Jika setiap retry atau replay membuat salinan penuh seluruh state, biaya storage akan cepat naik. Copy-on-write lebih efisien: data hanya disalin saat ada perubahan, sedangkan bagian yang tidak berubah tetap mereferensikan versi lama.

Contoh alur sederhananya:

  1. Job memuat aggregate order versi 42.
  2. Sistem membuat reference snapshot ke versi 42.
  3. Job mengubah status order dan reservation stok.
  4. Hanya field atau record yang berubah ditulis sebagai versi baru.
  5. Trace menyimpan pointer ke parent snapshot dan daftar perubahan.

Dengan model ini, Anda bisa:

  • mereplay job dari versi tertentu,
  • membuat fork untuk mencoba logika baru tanpa menyentuh state produksi,
  • melihat perbedaan antar percobaan secara eksplisit.

Apa yang perlu disnapshot

Jangan mencoba mensnapshot seluruh infrastruktur. Mulai dari state yang paling sering menjadi sumber insiden:

  • payload job yang sudah dinormalisasi,
  • row atau aggregate yang akan diubah,
  • metadata lock,
  • nilai cache yang dipakai untuk keputusan,
  • respon eksternal yang dikonsumsi sebelum mutasi state.

Untuk cache, menyimpan cache key dan cache version sering lebih praktis daripada menyalin seluruh cache global.

Idempotency key: syarat wajib agar retry tidak merusak state

Retry aman tidak bisa hanya mengandalkan “semoga job tidak diproses dua kali”. Anda perlu idempotency key yang stabil untuk setiap operasi yang boleh diulang.

Prinsip dasarnya

  • Satu niat bisnis menghasilkan satu idempotency key, misalnya order:123:charge.
  • Key harus tetap sama lintas retry untuk operasi yang sama.
  • Hasil operasi pertama disimpan agar percobaan berikutnya bisa mendeteksi bahwa efeknya sudah pernah dilakukan.

Contoh struktur tabel generik:

idempotency_records
- key
- operation_type
- status            // started, succeeded, failed
- result_ref        // pointer ke hasil jika perlu
- started_at
- completed_at
- trace_id

Saat worker akan mengeksekusi langkah yang memicu side effect, lakukan:

  1. cek apakah key sudah succeeded;
  2. jika ya, gunakan hasil sebelumnya atau tandai langkah sebagai no-op;
  3. jika belum, tandai started secara atomik lalu lanjutkan;
  4. setelah sukses, update ke succeeded.

Ini mengurangi risiko email terkirim dua kali, tagihan terdebet dua kali, atau resource eksternal dibuat berulang.

Kesalahan umum

  • Menggunakan random UUID per retry, sehingga idempotency kehilangan fungsi.
  • Menyimpan key tanpa konteks operasi, lalu dua aksi berbeda bentrok.
  • Menganggap idempotency key menggantikan locking. Tidak. Idempotency mencegah duplikasi efek, tetapi tidak otomatis mencegah race pada state lokal.

Strategi locking untuk mencegah race condition antar worker

Lock bukan hanya acquire dan release

Pada sistem queue, lock sering gagal bukan karena mekanismenya tidak ada, tetapi karena detail operasionalnya lemah: TTL terlalu pendek, tidak ada perpanjangan lease, atau worker crash tanpa mekanisme fencing.

Strategi minimum yang lebih aman:

  • Lease dengan TTL: lock punya masa berlaku agar tidak menggantung selamanya.
  • Heartbeat/renewal: worker aktif memperpanjang lease selama masih memegang lock.
  • Owner token: hanya pemilik lock yang boleh melepaskan atau memperpanjangnya.
  • Fencing token: setiap lock baru punya nomor monotonik; writer dengan token lebih tua harus ditolak oleh penyimpanan atau layanan target jika memungkinkan.

Kapan memakai lock per job dan kapan per resource

  • Lock per job cocok untuk mencegah job yang sama diproses bersamaan.
  • Lock per resource cocok saat banyak job berbeda memodifikasi entitas yang sama, misalnya order, akun, atau inventory item.

Jika akar masalah Anda adalah race condition antar worker, lock per job saja biasanya tidak cukup. Dua job berbeda tetap bisa menabrak resource yang sama.

Kombinasi lock dan optimistic concurrency

Desain yang sehat tidak hanya mengandalkan lock distribusi. Simpan juga version check pada state yang dimutasi. Misalnya update hanya sukses jika versi row yang dibaca sebelumnya masih sama. Jika tidak, hasilkan conflict yang eksplisit dan bisa direplay.

// pseudo-code generik
state = loadOrder(orderId)
trace.record("load_order", { version: state.version })

if !acquireResourceLock("order:" + orderId):
  retryLater("lock_unavailable")

updated = updateOrderWhereVersionMatches(
  orderId,
  expectedVersion = state.version,
  patch = { status: "paid" }
)

if !updated:
  trace.record("write_conflict", { expectedVersion: state.version })
  retryLater("optimistic_conflict")

Meskipun dua worker lolos dari lock akibat lease yang kedaluwarsa, version check tetap memberi pagar tambahan agar write lama tidak menimpa write baru secara diam-diam.

Replay aman: bedakan simulasi, dry-run, dan re-execution

Replay paling berbahaya adalah replay yang tanpa sadar mengulang side effect ke sistem nyata. Karena itu, pisahkan mode replay dengan jelas.

1. Trace replay

Mode ini hanya memutar ulang jejak keputusan untuk analisis. Tidak ada mutasi state dan tidak ada panggilan eksternal baru. Cocok untuk menjawab: “langkah mana yang gagal?”

2. Deterministic dry-run

Job dijalankan ulang dengan state snapshot dan dependensi eksternal disubstitusi dari trace sebelumnya atau stub. Mode ini cocok untuk menguji apakah kode baru menyelesaikan bug tanpa mengubah sistem nyata.

3. Forked re-execution

Sistem membuat cabang state dari snapshot tertentu, lalu menjalankan job dengan logika baru atau konfigurasi berbeda. Cocok untuk membandingkan hasil antara percobaan asli dan hasil perbaikan.

4. Real re-execution

Job dijalankan ulang ke sistem nyata, dengan guardrail ketat: idempotency key, lock, rate limit, dan daftar side effect yang diizinkan. Ini seharusnya menjadi opsi terakhir, bukan langkah pertama debugging.

Catatan: jangan jadikan replay sebagai pengganti postmortem. Replay membantu membuktikan urutan kejadian, tetapi runbook tetap harus menjelaskan keputusan operator: kapan job di-replay, kapan difork, dan kapan harus dihentikan.

Aturan aman untuk replay

  • Default ke mode non-destruktif.
  • Blok akses ke endpoint pembayaran, email, webhook, atau integrasi sensitif kecuali eksplisit diizinkan.
  • Pasang namespace terpisah untuk cache, queue, dan storage hasil replay.
  • Tandai trace hasil replay agar tidak tercampur dengan telemetry produksi.
  • Simpan peta antara trace asli dan trace turunan hasil fork.

Contoh alur implementasi generik pada backend queue

Berikut alur implementasi yang cukup generik untuk kebanyakan sistem backend:

1. Saat job dibuat

  • Normalisasi payload.
  • Buat trace_id dan causation/correlation id.
  • Simpan payload terkanonisasi ke trace store.
  • Hitung idempotency key untuk operasi penting.

2. Saat worker mulai memproses

  • Catat event job_started.
  • Ambil lock per resource jika perlu.
  • Baca snapshot state awal atau catat versi resource.

3. Sebelum setiap side effect

  • Tulis event step_started.
  • Cek idempotency key.
  • Jika memanggil layanan eksternal, simpan request metadata minimum dan response reference.

4. Setelah mutasi state

  • Simpan delta atau snapshot baru.
  • Catat event state_changed dengan pointer ke versi baru.
  • Validasi bahwa versi resource sesuai ekspektasi.

5. Jika gagal

  • Klasifikasikan kegagalan: transient, concurrency, validation, dependency, unknown.
  • Catat alasan retry yang eksplisit.
  • Jika aman, jadwalkan retry dengan backoff.
  • Jika tidak aman, pindahkan ke antrian investigasi atau dead-letter queue.

6. Untuk debugging insiden

  • Ambil trace job yang gagal.
  • Replay tanpa side effect untuk melihat urutan kejadian.
  • Fork dari snapshot sebelum langkah bermasalah.
  • Jalankan kode yang sudah diperbaiki terhadap fork tersebut.
  • Bandingkan delta state antara eksekusi asli dan hasil fork.
// pseudo-code worker generik
function process(job) {
  trace = traceStore.start(job)
  lock = lockManager.acquire(job.resourceKey)

  try {
    snapshot = stateStore.captureReference(job.resourceKey)
    trace.record("snapshot_captured", { snapshotRef: snapshot.ref })

    result = executeSteps(job, trace, snapshot)

    trace.record("job_succeeded", { resultRef: result.ref })
  } catch (err) {
    category = classify(err)
    trace.record("job_failed", {
      errorType: category,
      message: safeErrorMessage(err)
    })

    if (shouldRetry(category)) {
      scheduleRetry(job)
      trace.record("retry_scheduled")
    } else {
      moveToInvestigationQueue(job)
      trace.record("moved_to_investigation")
    }
  } finally {
    lockManager.releaseIfOwner(lock)
    trace.finish()
  }
}

Menangani kasus nyata yang sering muncul

Job gagal intermiten

Masalah ini sering terlihat acak padahal tidak. Dengan trace, Anda bisa melihat apakah kegagalan selalu muncul setelah pembacaan cache tertentu, hanya terjadi pada attempt kedua, atau selalu mengikuti lock renewal yang terlambat. Simpan metadata jaringan dan timeout secara ringkas agar pola ini terlihat.

Retry mengubah state

Biasanya disebabkan operasi tidak idempoten atau checkpoint yang buruk. Solusinya: pisahkan langkah baca, keputusan, dan side effect; pasang idempotency key pada side effect; dan catat apakah langkah sudah pernah berhasil pada attempt sebelumnya.

Lock kedaluwarsa

Jika TTL lock lebih pendek dari durasi kerja normal, worker kedua bisa masuk saat worker pertama belum selesai. Tanda-tandanya adalah dua trace berbeda mengubah resource yang sama dalam jendela waktu berdekatan. Perbaiki dengan heartbeat, TTL yang realistis, dan fencing token bila memungkinkan.

Cache tidak konsisten

Jangan hanya merekam “cache hit”. Rekam key, versi, dan waktu baca. Dalam replay, Anda bisa memutuskan apakah akan memakai nilai cache asli dari trace atau memaksa bypass ke snapshot sumber data. Ini membantu membedakan bug cache invalidation dari bug logika aplikasi.

Race condition antar worker

Trace yang baik harus menunjukkan happens-before relationship: siapa mengambil lock dulu, siapa membaca versi berapa, siapa menulis lebih dahulu. Tanpa ini, race condition sering tampak seperti bug acak yang tidak bisa direproduksi.

Metrik minimum yang perlu dipantau

Tanpa metrik, replay hanya membantu setelah insiden terjadi. Metrik membantu mendeteksi pola lebih awal.

  • retry rate per job type
  • dead-letter rate
  • lock acquisition latency
  • lock expiration before completion
  • idempotency conflict count
  • optimistic write conflict count
  • cache hit dengan stale detection
  • replay success rate di lingkungan investigasi
  • fork divergence rate: seberapa sering hasil fork berbeda dari eksekusi asli

Metrik ini tidak harus rumit. Yang penting cukup untuk membedakan tiga kelas masalah: dependency issue, concurrency issue, dan logic issue.

Runbook minimal untuk insiden queue

Berikut runbook sederhana yang realistis untuk tim backend:

  1. Identifikasi: ambil trace_id, job_id, attempt, resource key, dan waktu kejadian.
  2. Karantina: hentikan replay nyata otomatis untuk jenis job yang sama jika ada indikasi side effect berulang.
  3. Klasifikasi: tentukan apakah masalahnya transient, concurrency, state corruption, atau external dependency.
  4. Replay aman: jalankan trace replay atau dry-run dari snapshot terkait.
  5. Fork investigasi: buat cabang state sebelum langkah gagal, lalu uji patch atau konfigurasi baru.
  6. Bandingkan hasil: cek perbedaan state, lock timeline, dan side effect marker.
  7. Tentukan aksi: retry nyata, kompensasi, manual repair, atau drop job.
  8. Tutup insiden: simpan akar masalah, perubahan runbook, dan trace contoh untuk regresi test.

Runbook ini sederhana, tetapi jauh lebih baik daripada mengandalkan log teks dan retry manual berulang.

Trade-off biaya, storage, dan kompleksitas operasional

Biaya storage

Trace dan snapshot bisa tumbuh cepat. Jika semua payload, response, dan delta disimpan tanpa kebijakan retensi, biaya akan naik signifikan. Solusinya:

  • simpan event kecil di trace store cepat dicari,
  • offload blob besar ke object storage,
  • gunakan retensi bertingkat: detail penuh untuk beberapa hari, agregat untuk lebih lama,
  • kompres snapshot dan deduplikasi dengan copy-on-write.

Kompleksitas implementasi

Replayable worker queue menambah lapisan desain: trace schema, snapshot store, mode replay, dan guardrail side effect. Ini tidak gratis. Untuk sistem kecil, Anda mungkin cukup mulai dari idempotency, structured trace, dan version check sebelum menambah forkable snapshot.

Beban operasional

Operator dan engineer harus paham perbedaan antara retry biasa, replay aman, dan re-execution nyata. Jika istilah dan prosedurnya kabur, fitur replay justru menambah risiko insiden baru.

Batasan teknis

Tidak semua hal bisa dibuat deterministik. Waktu sistem, random number, urutan thread, respon layanan pihak ketiga, dan event eksternal tetap bisa berubah. Karena itu, target praktisnya bukan “replay 100% identik”, melainkan cukup deterministik untuk menjelaskan dan menguji insiden secara aman.

Langkah adopsi bertahap yang masuk akal

Jika sistem queue Anda belum punya fondasi ini, jangan langsung membangun semuanya sekaligus. Urutan adopsi yang lebih realistis:

  1. Tambahkan structured trace untuk lifecycle job dan langkah domain penting.
  2. Pasang idempotency key pada side effect utama.
  3. Perbaiki locking dengan owner token, renewal, dan version check.
  4. Simpan snapshot referensial untuk resource yang paling sering bermasalah.
  5. Buat mode dry-run replay yang memblok side effect eksternal.
  6. Tambahkan forked replay untuk investigasi kasus yang kompleks.

Dengan pendekatan bertahap, Anda mendapat manfaat debugging lebih cepat tanpa langsung menanggung seluruh biaya kompleksitas.

Penutup

Replayable Worker Queue bukan fitur mewah, tetapi respons teknis terhadap masalah nyata di sistem asynchronous: retry yang merusak state, lock yang bocor, cache yang menyesatkan, dan race condition yang sulit direproduksi. Desain yang baik menggabungkan event trace terstruktur, snapshot atau copy-on-write, idempotency key, locking yang disiplin, dan replay yang aman dari side effect.

Jika Anda harus memilih prioritas, mulai dari tiga hal: trace yang bisa ditelusuri, idempotency yang konsisten, dan versioned state. Tiga fondasi itu sudah cukup untuk mengubah debugging queue dari tebak-tebakan menjadi investigasi yang bisa dibuktikan.