Troubleshooting
| Gejala | Kemungkinan penyebab | Pemeriksaan dan tindakan |
|---|---|---|
Log Redis disabled in config atau bootstrap dilewati | REDIS_ENABLED tidak bernilai true. | Set REDIS_ENABLED=true, periksa host, port, credential, lalu restart worker. |
| Cache kosong setelah startup | Tidak ada row kv_cache_table yang published/aktif, tabel tidak tercatat di directus_collections, atau query gagal. | Periksa metadata tersebut dan cari log Failed to fetch rows atau SQL Guard Blocked Query. |
query_source ditolak | Query kosong, bukan SELECT/WITH, mengandung keyword write/DDL, atau string dollar-quoted tidak ditutup. | Ubah query menjadi read-only dan uji kembali; hasil wajib menyediakan kolom id. |
| Row tidak masuk cache | Row tidak memiliki id; pada realtime default, status bukan published. | Pastikan hasil query memiliki id dan status sesuai aturan. |
| Listener realtime tidak aktif | NATS_ENABLED nonaktif, NATS_URL salah, bootstrap belum membuka barrier, atau stream tidak dapat dibuat. | Periksa log koneksi NATS, Startup barrier opened, dan keberadaan stream PG_CDC_EVENTS. |
| Event item terus dikirim ulang | Query database, operasi Redis, atau publish path melempar error. | Cari log subject terkait; consumer melakukan nak(10000) dengan maksimal tiga delivery. |
Perubahan kv_cache_table gagal tetapi tidak retry | Consumer metadata meng-ack message pada catch path. | Perbaiki penyebab dari log lalu picu event baru atau restart untuk bootstrap ulang. |
| Key tampak hilang | CACHE_PREFIX aktif. | Cari <prefix>:config.<cache>.*; global:config tetap tanpa prefix. |
global:config berbeda dari key per-row | Pembaruan key row, index, dan snapshot tidak atomik, atau proses terhenti di tengah operasi. | Restart worker agar purge dan bootstrap membentuk ulang cache dari database. |
| Tabel tidak lagi menerima CDC | Row registrasinya tidak ada di cache kv_cache_table, sehingga subscription dinamis dilepas. | Periksa row kv_cache_table, status/date_deleted, dan index cache metadata. |
Catatan event delete metadata
KvCacheTableService membaca after.id sebelum membedakan operasi. Bila producer mengirim bentuk delete Debezium standar dengan after = null, pemrosesan masuk catch path lalu message di-ack. Pastikan kontrak producer menyediakan after untuk subject ini, atau verifikasi perilaku ini sebelum mengandalkan hard delete metadata. Soft delete melalui operasi update dengan date_deleted adalah jalur yang secara eksplisit ditangani source.
Pemulihan paling sederhana
Untuk inkonsistensi cache, restart worker-common. Startup akan mencoba menghapus key konfigurasi dan membangun ulang snapshot dari PostgreSQL sebelum listener realtime dibuka.