Flag AI tak sinkron karena cache konfigurasi biasanya muncul sebagai gejala yang membingungkan: sebagian user melihat toggle aktif, request berikutnya masih diproses seolah fitur mati, hasil eksperimen A/B berubah-ubah, dan rollback terasa lambat walau panel admin sudah diperbarui. Dalam sistem backend yang berjalan di beberapa proses atau beberapa node, masalah ini hampir selalu berhubungan dengan state konfigurasi yang tersebar dan tidak diperbarui secara konsisten.

Solusi jangka panjangnya bukan sekadar “bersihkan cache”, melainkan memastikan ada single source of truth, versi konfigurasi yang eksplisit, mekanisme invalidasi yang dapat diaudit, serta observability yang memperlihatkan flag mana yang dipakai oleh setiap request. Artikel ini membahas pola bug yang umum, cara menginvestigasinya, contoh alur kegagalan, dan pendekatan perbaikan yang lebih tahan terhadap rollback dan deploy multi-node.

Gejala nyata saat feature flag AI toggle tidak sinkron

Masalah ini jarang muncul sebagai error yang jelas. Backend tetap berjalan normal, tetapi perilakunya tidak konsisten. Beberapa gejala yang sering terlihat:

  • UI admin menampilkan toggle AI aktif, tetapi endpoint inferensi atau routing model masih membaca nilai lama.
  • Antar request hasilnya berbeda untuk user yang sama karena request pertama masuk ke node A dan request berikutnya ke node B.
  • Eksperimen A/B menjadi kotor karena assignment user dihitung memakai konfigurasi baru, tetapi eksekusi fitur memakai cache lama.
  • Rollback lambat karena perubahan flag sudah disimpan di database, namun worker, API node, atau edge cache belum mengambil nilai terbaru.
  • Log aplikasi terlihat normal, tetapi metrik bisnis menunjukkan penurunan adopsi atau lonjakan fallback yang tidak sesuai ekspektasi rollout.

Ini berbahaya karena tim sering salah membaca sinyal. Mereka mengira masalah ada pada model AI, load balancer, atau frontend, padahal akar persoalannya adalah pembacaan konfigurasi yang tidak deterministik.

Arsitektur yang sering memicu bug

Bug ini umum terjadi ketika konfigurasi flag dibaca dari satu tempat, lalu disalin ke beberapa lapisan cache:

  • Database atau service konfigurasi sebagai sumber utama.
  • Cache terdistribusi seperti Redis atau Memcached.
  • Cache in-memory di proses aplikasi untuk mengurangi latensi.
  • Worker background yang memuat konfigurasi saat startup dan jarang refresh.
  • CDN atau edge layer yang ikut menyimpan respons terkait status fitur.

Semakin banyak lapisan cache, semakin besar peluang terjadinya ketidaksinkronan jika tidak ada aturan invalidasi yang jelas. TTL panjang memang mengurangi beban ke sumber utama, tetapi memperbesar jendela inkonsistensi saat flag diubah cepat, terutama saat rollout bertahap atau rollback darurat.

Pola kegagalan yang paling sering

  • TTL terlalu panjang: perubahan sudah tersimpan, tetapi node lain masih memegang nilai lama selama beberapa menit.
  • Invalidasi gagal diam-diam: event publish berhasil di satu proses, tetapi subscriber di proses lain putus koneksi atau gagal memproses pesan.
  • Race condition saat reload config: sebagian request memakai snapshot lama, sebagian memakai snapshot baru, dan state antara evaluator dan executor tidak cocok.
  • Perbedaan source of truth: UI menulis ke database, API membaca dari Redis, worker membaca file lokal atau env yang tidak ikut berubah.
  • Sticky cache per worker: proses yang hidup lama tidak melakukan refresh, sehingga nilai flag “membeku” sampai restart.

Root cause yang patut dicurigai

1. Cache konfigurasi terlalu agresif

Ini skenario paling umum. Untuk menghindari query berulang, aplikasi menyimpan konfigurasi flag dalam cache in-memory atau Redis dengan TTL besar. Ketika admin mengaktifkan AI toggle, perubahan memang langsung tersimpan, tetapi request yang masuk ke node lain masih membaca versi lama sampai TTL habis.

Masalah makin parah jika ada dua level cache: Redis TTL 60 detik dan in-memory TTL 300 detik. Tim mungkin hanya menghapus Redis, padahal proses aplikasi masih menyajikan nilai dari memori lokal.

2. Invalidasi cache tidak andal

Sebagian sistem mengandalkan event seperti config_updated untuk membatalkan cache di semua node. Pendekatan ini efisien, tetapi rentan jika tidak ada jaminan pengiriman atau pengecekan keberhasilan. Bila satu node gagal menerima event, node itu akan tetap memakai nilai lama lebih lama dari yang diperkirakan.

Catatan: invalidasi berbasis event tanpa mekanisme verifikasi sering tampak bekerja di lingkungan kecil, lalu mulai bermasalah ketika jumlah node, worker, atau region bertambah.

3. Race condition saat reload

Bug jenis ini lebih halus. Misalnya evaluator flag memuat config baru, tetapi komponen yang mengeksekusi fitur masih memegang snapshot lama. Akibatnya log bisa menyebut “flag enabled=true”, tetapi branch eksekusi masih menuju fallback non-AI karena dependency lain belum ikut diperbarui.

4. Sumber kebenaran berbeda

UI admin sering dianggap benar karena menampilkan nilai terbaru dari database. Namun backend produksi bisa jadi tidak membaca database yang sama pada jalur request kritis. Misalnya:

  • Admin panel menulis ke tabel feature_flags.
  • API runtime membaca salinan konfigurasi di Redis.
  • Worker asynchronous membaca file hasil snapshot periodik.

Dari sudut pandang operator, “toggle sudah aktif”. Dari sudut pandang runtime, masing-masing komponen punya jawaban berbeda.

Langkah investigasi yang benar

Saat menghadapi bug seperti ini, tujuan utama investigasi adalah menjawab tiga pertanyaan:

  1. Nilai flag apa yang dipakai request ini?
  2. Dari sumber mana nilai itu diambil?
  3. Versi konfigurasi berapa yang aktif di tiap node?

Tanpa tiga jawaban ini, debugging sering berputar pada tebakan.

1. Tambahkan jejak flag pada log request

Pastikan setiap request yang relevan mencatat:

  • nama flag, misalnya ai_toggle
  • nilai evaluasi akhir: enabled/disabled
  • sumber pembacaan: db, redis, memory, snapshot
  • versi konfigurasi atau timestamp terakhir
  • node ID / pod name / process ID
  • user ID atau request ID untuk korelasi

Contoh bentuk log terstruktur:

{
  "request_id": "req-8f2a",
  "user_id": "u-1024",
  "flag": "ai_toggle",
  "enabled": false,
  "config_version": 184,
  "config_source": "memory_cache",
  "node": "api-pod-3",
  "ts": "2026-08-09T10:15:03Z"
}

Log seperti ini memungkinkan Anda membuktikan bahwa request yang gagal memang memakai versi lama, bukan sekadar menduga.

2. Periksa metrik distribusi versi konfigurasi

Selain log per request, buat metrik agregat seperti:

  • jumlah request per config_version
  • jumlah node yang masih memakai versi lama
  • usia cache konfigurasi per node
  • jumlah kegagalan invalidasi cache
  • latensi propagasi perubahan flag sejak update sampai semua node memakai versi baru

Jika setelah toggle diubah masih ada request yang datang dengan dua versi berbeda, Anda sudah punya bukti ketidaksinkronan antar node.

3. Audit jalur update konfigurasi

Telusuri alurnya dari awal sampai akhir:

  1. UI/admin mengubah flag.
  2. Perubahan disimpan ke database atau service konfigurasi.
  3. Versi konfigurasi bertambah atau timestamp berubah.
  4. Event invalidasi dipublikasikan.
  5. Setiap node menerima event dan membuang cache lokal.
  6. Request berikutnya memuat nilai terbaru.

Setiap langkah perlu bukti. Jangan berhenti di “record database sudah berubah”. Banyak bug justru muncul setelah langkah itu.

4. Cocokkan perilaku per node

Pada sistem multi-node, kirim request berulang sambil memaksa trafik ke node yang berbeda jika memungkinkan. Tujuannya untuk melihat apakah hanya subset node yang stale. Pada lingkungan kontainer, Anda dapat membandingkan log per pod atau melakukan port-forward langsung ke pod tertentu untuk mengisolasi perbedaan.

5. Cek worker dan job asynchronous

Jangan fokus hanya ke API sinkron. Jika hasil AI dipicu oleh queue atau background worker, worker bisa jadi membaca konfigurasi yang lebih lama daripada web node. Ini menjelaskan kasus ketika endpoint pengaturan mengatakan fitur aktif, tetapi hasil proses di belakang layar masih mengikuti jalur non-AI.

Reproduksi lokal yang realistis

Bug cache konfigurasi lebih mudah dipahami jika direproduksi dalam skala kecil. Misalnya, jalankan dua instance API lokal yang sama-sama membaca flag dari Redis, tetapi masing-masing menyimpan salinan in-memory dengan TTL 5 menit.

Alurnya:

  1. Set ai_toggle=false.
  2. Kirim request ke instance A dan B agar keduanya mengisi cache lokal.
  3. Ubah flag menjadi true di database dan hapus cache Redis.
  4. Jangan restart instance A dan B.
  5. Kirim request lagi ke kedua instance.

Jika instance masih memakai cache in-memory, keduanya dapat tetap mengembalikan false meski Redis dan database sudah benar. Ini menunjukkan bahwa membersihkan cache bersama saja belum tentu cukup.

Contoh pseudocode alur bug

global localConfigCache
global localConfigFetchedAt
const TTL_SECONDS = 300

function getAiFlag(userId):
    if localConfigCache != null and now() - localConfigFetchedAt < TTL_SECONDS:
        return evaluate(localConfigCache, userId)

    sharedConfig = redis.get("feature_flags")
    if sharedConfig == null:
        sharedConfig = db.loadFeatureFlags()
        redis.set("feature_flags", sharedConfig, ttl=60)

    localConfigCache = sharedConfig
    localConfigFetchedAt = now()
    return evaluate(localConfigCache, userId)

function updateAiFlag(enabled):
    db.update("ai_toggle", enabled)
    redis.del("feature_flags")
    publish("config_updated")

Masalahnya jelas: updateAiFlag hanya menghapus Redis, tetapi tidak menjamin semua proses menghapus localConfigCache. Bahkan jika event config_updated dikirim, tidak ada bukti semua subscriber menerimanya.

Contoh race condition saat reload

function onConfigUpdated(newConfig):
    currentFlags = newConfig.flags
    // evaluator memakai currentFlags baru
    // tetapi dependency routing model masih mengacu ke modelConfig lama
    // hasil: flag menyatakan enabled, executor jatuh ke fallback
    reloadModelRoutingAsync(newConfig.modelRouting)

Jika pembaruan tidak atomik, request di tengah proses reload dapat melihat kombinasi state lama dan baru.

Perbaikan yang lebih tahan produksi

1. Tetapkan single source of truth

Pilih satu sumber kebenaran yang jelas untuk evaluasi flag pada runtime. Komponen lain boleh menjadi cache, tetapi tidak boleh punya logika penentuan akhir sendiri. Praktiknya bisa berupa service konfigurasi internal, database tertentu, atau store terdistribusi yang konsisten.

Yang penting, seluruh jalur request membaca model data yang sama dan dapat mengidentifikasi versinya.

2. Gunakan versioned config

Alih-alih hanya menyimpan nilai flag, simpan juga config_version yang bertambah setiap ada perubahan. Setiap node harus tahu versi mana yang sedang dipakai. Dengan begitu:

  • log lebih mudah dikorelasikan
  • node stale lebih cepat terdeteksi
  • invalidasi bisa divalidasi, bukan diasumsikan
  • rollback dapat dipastikan mencapai semua node

Contoh struktur respons internal:

{
  "version": 185,
  "updated_at": "2026-08-09T10:20:00Z",
  "flags": {
    "ai_toggle": true
  }
}

Saat request diproses, lampirkan versi ini pada log dan, bila aman, pada header observability internal.

3. Cache busting berbasis versi, bukan hanya TTL

TTL tetap berguna sebagai batas aman, tetapi jangan menjadikannya satu-satunya mekanisme sinkronisasi. Pendekatan yang lebih andal adalah mengganti kunci cache berdasarkan versi:

feature_flags:v185

Node yang mengetahui ada versi baru tidak perlu menunggu TTL habis. Ia cukup memuat kunci versi terbaru. Strategi ini juga mengurangi risiko pembacaan campuran saat rollout cepat.

4. Reload atomik

Jika perubahan konfigurasi memengaruhi beberapa struktur data, bangun snapshot baru secara penuh lalu tukar referensi secara atomik. Hindari memperbarui bagian-bagian konfigurasi satu per satu di tengah request.

Prinsipnya:

  • buat objek config baru secara lengkap
  • validasi konsistensinya
  • publikasikan satu pointer/snapshot baru
  • request lama menyelesaikan eksekusi dengan snapshot lama, request baru memakai snapshot baru

Pola ini mengurangi race condition antara evaluator flag dan komponen eksekusi.

5. Buat invalidasi yang bisa diaudit

Jika memakai pub/sub atau event bus, catat:

  • siapa yang mempublikasikan update
  • versi berapa yang dipublikasikan
  • node mana yang sudah mengakui penerimaan
  • berapa lama waktu propagasi tiap node

Tanpa audit seperti ini, invalidasi tampak “mungkin berhasil”, tetapi sulit dibuktikan saat insiden.

6. Tambahkan fallback keselamatan untuk rollback

Rollback seharusnya tidak bergantung pada timeout cache yang panjang. Untuk flag berisiko tinggi seperti toggle AI, sediakan jalur darurat:

  • memaksa refresh config pada node
  • menonaktifkan flag dari source of truth yang dibaca sinkron
  • membatasi penggunaan cache lokal sementara waktu

Trade-off-nya adalah beban baca dapat naik sesaat, tetapi itu biasanya lebih murah daripada membiarkan perilaku salah berlanjut selama beberapa menit.

Observability yang sebaiknya ada sejak awal

Agar insiden serupa lebih cepat terdeteksi, backend perlu observability yang spesifik untuk feature flag, bukan hanya log aplikasi umum.

Checklist observability

  • Structured log untuk hasil evaluasi flag per request.
  • Metric cardinality terkontrol per flag dan per versi konfigurasi.
  • Dashboard propagasi: berapa node sudah pada versi terbaru.
  • Alert jika lebih dari satu versi aktif terlalu lama setelah update.
  • Trace annotation yang menandai keputusan feature flag pada request penting.

Dengan data ini, tim bisa membedakan apakah masalah ada pada UI admin, service config, cache, atau worker executor.

Tes regresi yang wajib ditambahkan

Bug seperti ini sering lolos karena unit test hanya memeriksa “flag true menghasilkan jalur AI” dan “flag false menghasilkan fallback”. Itu belum cukup. Anda perlu tes yang memodelkan perubahan konfigurasi di sistem berjalan.

1. Test propagasi antar node

Simulasikan dua instance aplikasi. Ubah flag di source of truth, lalu verifikasi keduanya berpindah ke versi baru dalam batas waktu yang dapat diterima.

2. Test cache invalidation failure

Paksa satu subscriber gagal menerima event invalidasi. Pastikan ada mekanisme pemulihan, misalnya refresh berkala berbasis versi atau pengecekan versi minimum saat request kritis.

3. Test rollback cepat

Aktifkan lalu nonaktifkan flag dalam rentang singkat. Pastikan sistem tidak tertinggal di status aktif karena event datang tidak berurutan atau cache lama masih menempel.

4. Test atomic reload

Verifikasi request tidak pernah melihat kombinasi state setengah lama dan setengah baru. Ini penting jika toggle AI juga mengubah routing model, quota, atau strategi fallback.

Contoh skenario uji tingkat integrasi

Given config version 10 with ai_toggle=false
And node A and node B have loaded version 10
When admin updates ai_toggle=true producing version 11
Then both nodes should eventually serve version 11
And no request after propagation window should log version 10
When admin rolls back to ai_toggle=false producing version 12
Then both nodes should eventually serve version 12

Kesalahan umum saat memperbaiki masalah ini

  • Hanya memperpendek TTL tanpa membenahi invalidasi dan versi konfigurasi.
  • Mengandalkan restart manual sebagai solusi rutin. Ini menutupi akar masalah dan berisiko saat insiden berikutnya.
  • Tidak mencatat sumber pembacaan config, sehingga sulit membedakan apakah data berasal dari DB, Redis, atau memori lokal.
  • Menganggap UI admin sebagai bukti runtime. Nilai yang tampil di panel belum tentu nilai yang dipakai request produksi.
  • Mencampur evaluasi flag dan side effect reload tanpa batas atomik yang jelas.

Penutup

Kasus flag AI tak sinkron karena cache konfigurasi adalah bug backend yang tampak kecil, tetapi efeknya besar: perilaku user tidak konsisten, eksperimen menjadi tidak valid, dan rollback kehilangan urgensinya. Penyebab utamanya biasanya bukan satu baris kode yang salah, melainkan desain distribusi konfigurasi yang terlalu optimistis terhadap cache dan invalidasi.

Pendekatan yang paling aman adalah memperlakukan feature flag sebagai data runtime yang harus memiliki single source of truth, config version, propagasi yang dapat diaudit, reload atomik, dan tes regresi lintas node. Jika setiap request bisa menjawab “flag apa yang dipakai, dari mana asalnya, dan versi berapa”, proses debugging akan jauh lebih cepat dan bug serupa lebih sulit terulang.