ID Korelasi end-to-end: lacak aksi pengguna di log

Mengapa ID korelasi penting untuk dukungan

Laporan bug dari pengguna hampir tidak pernah bersih. Pengguna bilang, "Saya klik Pay dan gagal," tetapi klik tunggal itu bisa menyentuh browser, API gateway, layanan pembayaran, basis data, dan job latar belakang. Setiap bagian mencatat bagiannya sendiri pada waktu yang berbeda, di mesin yang berbeda. Tanpa satu label bersama, Anda harus menebak baris log mana yang saling terkait.

ID korelasi adalah label bersama itu. Ini satu ID yang ditempelkan ke satu aksi pengguna (atau satu workflow logis) dan dibawa melalui setiap permintaan, retry, dan lompatan layanan. Dengan cakupan end-to-end yang benar, Anda bisa mulai dari keluhan pengguna dan menarik seluruh garis waktu lintas sistem.

Orang sering mencampur beberapa ID yang mirip. Berikut pemisahan yang jelas:

• Correlation ID: mengelompokkan semua yang terkait dengan satu aksi (misal, "Simpan pengaturan").
• Request ID: mengidentifikasi satu permintaan HTTP. Retry membuat request ID baru.
• Trace ID: digunakan oleh alat distributed tracing; tujuan serupa, sering dihasilkan oleh library tracing.
• Session ID: mengidentifikasi sesi pengguna sepanjang banyak aksi; terlalu luas untuk men-debug satu insiden.

Yang baik terlihat sederhana: pengguna melaporkan masalah, Anda minta mereka ID korelasi yang ditampilkan di UI (atau ditemukan di layar dukungan), dan siapa pun di tim bisa menemukan seluruh cerita dalam hitungan menit. Anda melihat permintaan frontend, respons API, langkah backend, dan hasil basis data, semuanya terhubung.

Tentukan konvensi ID korelasi Anda

Sebelum membuat apa pun, sepakati beberapa aturan. Jika setiap tim memilih nama header atau field log yang berbeda, dukungan tetap akan kebingungan menebak.

Mulai dengan satu nama kanonis dan gunakan di mana-mana. Pilihan umum adalah header HTTP seperti X-Correlation-Id, plus field log terstruktur seperti correlation_id. Pilih satu ejaan dan satu kapitalisasi, dokumentasikan, dan pastikan reverse proxy atau gateway Anda tidak mengganti nama atau menghapus header itu.

Pilih format yang mudah dibuat dan aman untuk dibagikan di tiket dan chat. UUID bekerja baik karena unik dan membosankan. Buat ID cukup pendek untuk disalin, tetapi tidak terlalu pendek sehingga berisiko tabrakan. Konsistensi lebih penting daripada kepintaran.

Juga putuskan di mana ID harus muncul agar manusia benar-benar bisa menggunakannya. Dalam praktiknya, itu berarti hadir di permintaan, log, dan output error, serta dapat dicari di alat yang tim Anda gunakan.

Tentukan juga berapa lama satu ID harus hidup. Default yang baik adalah satu aksi pengguna, seperti "klik Pay" atau "simpan profil." Untuk workflow yang lebih panjang yang melintasi layanan dan antrean, pertahankan ID yang sama sampai workflow selesai, lalu mulai yang baru untuk aksi berikutnya. Hindari "satu ID untuk seluruh sesi" karena pencarian akan cepat menjadi bising.

Satu aturan keras: jangan pernah memasukkan data pribadi dalam ID. Tidak ada email, nomor telepon, user ID, atau nomor pesanan. Jika Anda perlu konteks itu, catat di field terpisah dengan kontrol privasi yang tepat.

Hasilkan ID di frontend (pendekatan praktis)

Tempat termudah untuk memulai ID korelasi adalah saat pengguna memulai aksi yang Anda pedulikan: klik "Simpan", submit form, atau memicu alur yang memunculkan banyak permintaan. Jika Anda menunggu backend membuatnya, sering bagian awal cerita (error UI, retry, request yang dibatalkan) akan hilang.

Gunakan format acak dan unik. UUID v4 adalah pilihan umum karena mudah dibuat dan kecil kemungkinannya bertabrakan. Buat ID bersifat opak (tanpa username, email, atau cap waktu) agar Anda tidak membocorkan data pribadi ke header dan log.

Buat dan pertahankan ID untuk satu workflow

Anggap "workflow" sebagai satu aksi pengguna yang mungkin memicu beberapa permintaan: validasi, upload, buat record, lalu refresh daftar. Buat satu ID saat workflow dimulai, lalu pertahankan sampai workflow selesai (sukses, gagal, atau pengguna membatalkan). Pola sederhana adalah menyimpannya di state komponen atau objek konteks permintaan ringan.

Jika pengguna memulai aksi yang sama dua kali, buat ID korelasi baru untuk percobaan kedua. Itu membantu dukungan membedakan "klik sama yang diretry" dari "dua submit terpisah."

Lampirkan ke setiap permintaan yang dibuat oleh workflow itu

Tambahkan ID ke setiap panggilan API yang dipicu oleh workflow, biasanya lewat header seperti X-Correlation-ID. Jika Anda menggunakan client API bersama (wrapper fetch, instance Axios, dll.), operkan ID sekali dan biarkan client menyuntikkannya ke semua panggilan.

// 1) when the user action starts
const correlationId = crypto.randomUUID(); // UUID v4 in modern browsers

// 2) pass it to every request in this workflow
await api.post('/orders', payload, {
  headers: { 'X-Correlation-ID': correlationId }
});

await api.get('/orders/summary', {
  headers: { 'X-Correlation-ID': correlationId }
});

Jika UI Anda membuat permintaan latar yang tidak terkait dengan aksi (polling, analytics, auto-refresh), jangan gunakan kembali ID workflow itu untuk permintaan tersebut. Fokuskan ID korelasi sehingga satu ID menceritakan satu kisah.

Lewarkan ID lewat API Anda secara andal

Setelah Anda membuat ID di browser, tugasnya sederhana: ID itu harus keluar dari frontend pada setiap permintaan dan tiba tanpa perubahan di setiap boundary API. Inilah yang paling sering rusak ketika tim menambah endpoint, klien baru, atau middleware baru.

Default paling aman adalah header HTTP pada setiap panggilan (mis. X-Correlation-Id). Header mudah ditambahkan di satu tempat (wrapper fetch, interceptor Axios, lapisan jaringan mobile) dan tidak memerlukan perubahan payload.

Jika Anda memiliki permintaan lintas-origin, pastikan API mengizinkan header itu. Kalau tidak, browser mungkin diam-diam memblokirnya dan Anda akan mengira sudah mengirimkannya padahal tidak.

Jika Anda harus meletakkan ID di query string atau body permintaan (beberapa tool pihak ketiga atau upload file memaksakan ini), jaga konsistensi dan dokumentasikan. Pilih satu nama field dan gunakan di mana-mana. Jangan mencampur correlationId, requestId, dan cid bergantung pada endpoint.

Retry adalah perangkap umum lain. Retry harus mempertahankan ID korelasi jika masih aksi pengguna yang sama. Contoh: pengguna klik "Simpan", jaringan terputus, client Anda melakukan retry POST. Dukungan harus melihat satu jejak terhubung, bukan tiga yang tidak terkait. Klik pengguna baru (atau job background baru) harus mendapat ID baru.

Untuk WebSocket, sertakan ID dalam envelope pesan, tidak hanya pada handshake awal. Satu koneksi dapat membawa banyak aksi pengguna.

Jika Anda ingin cek keandalan cepat, buatlah sederhana:

• Satu helper client bersama menambah header pada setiap permintaan.
• Retry menggunakan ID yang sama untuk aksi yang sama.
• Setiap fallback body/query menggunakan satu nama field yang didokumentasikan.
• Pesan WebSocket menyertakan field correlationId yang eksplisit.

Atur perilaku entry point API

Edge API Anda (gateway, load balancer, atau layanan web pertama yang menerima traffic) adalah tempat ID korelasi menjadi dapat diandalkan atau berubah menjadi tebakan. Perlakukan titik masuk ini sebagai sumber kebenaran.

Terima ID yang masuk jika klien mengirimkannya, tetapi jangan anggap selalu ada. Jika tidak ada, buat satu ID baru segera dan gunakan untuk sisa permintaan. Ini menjaga agar sistem tetap bekerja meski beberapa klien lebih tua atau salah konfigurasi.

Lakukan validasi ringan agar nilai buruk tidak mencemari log Anda. Jadikan permisif: periksa panjang dan karakter yang diizinkan, tapi hindari format ketat yang menolak traffic nyata. Misalnya, izinkan 16–64 karakter dan huruf, angka, dash, serta underscore. Jika nilai gagal validasi, gantikan dengan ID baru dan lanjutkan.

Buat ID terlihat oleh pemanggil. Selalu kembalikan di header respons, dan sertakan di body error. Dengan begitu pengguna dapat menyalinnya dari UI, atau agen dukungan dapat memintanya dan menemukan jejak log yang tepat.

Kebijakan edge praktis terlihat seperti ini:

• Baca X-Correlation-ID (atau header pilihan Anda) dari permintaan.
• Jika hilang atau tidak valid, buat ID baru dan lampirkan ke konteks permintaan.
• Tambahkan X-Correlation-ID ke setiap respons, termasuk error.
• Saat mengembalikan error JSON, ulangi ID di payload.

Contoh payload error (yang sebaiknya dilihat dukungan di tiket dan screenshot):

{
  "error": {
    "code": "PAYMENT_FAILED",
    "message": "We could not confirm the payment.",
    "correlation_id": "c3a8f2d1-9b24-4c61-8c4a-2a7c1b9c2f61"
  }
}

Propagasi ID ke seluruh layanan backend

Setelah permintaan mencapai backend Anda, perlakukan ID korelasi sebagai bagian dari konteks permintaan, bukan sesuatu yang Anda taruh di variabel global. Global akan rusak saat Anda menangani dua permintaan sekaligus atau saat kerja async berlanjut setelah respons.

Aturan yang skala: setiap fungsi yang dapat melakukan log atau memanggil layanan lain harus menerima konteks yang berisi ID. Di layanan Go, itu biasanya berarti meneruskan context.Context melalui handler, logika bisnis, dan kode client.

Saat Service A memanggil Service B, salin ID yang sama ke permintaan keluar. Jangan hasilkan yang baru di tengah perjalanan kecuali Anda juga menyimpan yang asli sebagai field terpisah (mis. parent_correlation_id). Jika Anda mengubah ID, dukungan kehilangan benang tunggal yang mengikat cerita bersama.

Propagasi sering terlewat di beberapa tempat yang bisa diprediksi: job latar yang dipicu saat permintaan, retry di dalam library client, webhook yang dipicu nanti, dan panggilan fan-out. Setiap pesan async (queue/job) harus membawa ID, dan setiap logika retry harus mempertahankannya.

Log harus terstruktur dengan nama field stabil seperti correlation_id. Pilih satu ejaan dan pertahankan di mana-mana. Hindari mencampur requestId, req_id, dan traceId kecuali Anda juga mendefinisikan pemetaan yang jelas.

Jika memungkinkan, sertakan ID di visibilitas basis data juga. Pendekatan praktis adalah menambahkannya ke komentar query atau metadata sesi sehingga slow query log dapat menunjukkannya. Ketika seseorang melaporkan "Tombol Simpan macet selama 10 detik," dukungan bisa mencari correlation_id=abc123 dan melihat log API, panggilan layanan hilir, dan satu pernyataan SQL lambat yang jadi penyebab.

Sertakan ID di log yang bisa digunakan manusia

ID korelasi hanya membantu jika orang bisa menemukannya dan mengikutinya. Jadikan itu field log kelas utama (bukan terkubur dalam string pesan), dan jaga agar entri log lain konsisten di seluruh layanan.

Field log yang membuat ID bisa dipakai

Padukan ID korelasi dengan beberapa field kecil yang menjawab: kapan, di mana, apa, dan siapa (dengan cara yang aman untuk pengguna). Untuk kebanyakan tim, itu berarti:

• timestamp (dengan zona waktu)
• service dan env (api, worker, prod, staging)
• route (atau nama operasi) dan method
• status dan duration_ms
• identifier yang aman untuk pengguna (mis. account_id atau user id yang di-hash, bukan email)

Dengan ini, dukungan bisa mencari berdasarkan ID, memastikan mereka melihat permintaan yang tepat, dan melihat layanan mana yang menanganinya.

Apa yang dicatat saat mulai, sukses, dan gagal

Sasar beberapa breadcrumb kuat per permintaan, bukan transkrip lengkap.

• Start: correlation ID, route, identifier pengguna yang aman, dan input kunci (disingkat).
• Success: correlation ID, status, durasi, dan hasil singkat (mis. rows=12).
• Failure: correlation ID, tipe error, konteks yang aman, dan di mana terjadi (handler, dependency).

Untuk menghindari log yang bising, simpan detail level debug non-aktif secara default dan promosikan hanya event yang membantu menjawab, "Di mana kegagalannya?" Jika satu baris tidak membantu menemukan masalah atau mengukur dampak, kemungkinan besar tidak perlu berada di log level info.

Redaksi sama pentingnya dengan struktur. Jangan pernah memasukkan PII ke dalam ID korelasi atau log: tidak ada email, nama, nomor telepon, alamat lengkap, atau token mentah. Jika perlu mengidentifikasi pengguna, log ID internal atau hash satu-arah.

Contoh: menelusuri satu laporan pengguna dari UI ke database

Seorang pengguna menghubungi dukungan: "Checkout gagal saat saya klik Pay." Pertanyaan tindak lanjut terbaik sederhana: "Bisakah Anda menempelkan ID korelasi yang muncul di layar error?" Mereka membalas dengan cid=9f3c2b1f6a7a4c2f.

Dukungan sekarang punya pegangan yang menghubungkan UI, API, dan kerja basis data. Tujuannya adalah setiap baris log untuk aksi itu membawa ID yang sama.

Dukungan mencari log untuk 9f3c2b1f6a7a4c2f dan melihat alurnya:

frontend  INFO  cid=9f3c2b1f6a7a4c2f event="checkout_submit" cart=3 items
api       INFO  cid=9f3c2b1f6a7a4c2f method=POST path=/api/checkout user=1842
api       ERROR cid=9f3c2b1f6a7a4c2f msg="payment failed" provider=stripe status=502

Dari sana, engineer mengikuti ID yang sama ke hop berikutnya. Kuncinya adalah panggilan layanan backend (dan job antrean apa pun) juga meneruskan ID.

payments  INFO  cid=9f3c2b1f6a7a4c2f action="charge" amount=49.00 currency=USD
payments  ERROR cid=9f3c2b1f6a7a4c2f err="timeout" upstream=stripe timeout_ms=3000
db        INFO  cid=9f3c2b1f6a7a4c2f query="insert into failed_payments" rows=1

Sekarang masalah konkret: layanan pembayaran timeout setelah 3 detik, dan catatan kegagalan ditulis. Engineer bisa memeriksa deploy terbaru, memastikan apakah setting timeout berubah, dan melihat apakah retry terjadi.

Untuk menutup loop, lakukan empat pemeriksaan:

• Perbaiki penyebabnya (mis. sesuaikan timeout dan tambahkan retry yang aman).
• Pastikan error yang terlihat pengguna menyertakan ID korelasi.
• Pantau log baru dengan pola error yang sama dan ID berbeda.
• Konfirmasi ID bertahan di setiap hop (termasuk worker dan pesan antrean).

Kesalahan umum dan cara menghindarinya

Cara tercepat membuat ID korelasi tidak berguna adalah memutus rantai. Sebagian besar kegagalan berasal dari keputusan kecil yang terasa tidak berbahaya saat Anda membangun, lalu menyusahkan saat dukungan butuh jawaban.

Kesalahan klasik adalah membuat ID baru di setiap hop. Jika browser mengirim ID, gateway API Anda harus mempertahankannya, bukan menggantikannya. Jika benar-benar perlu ID internal juga (untuk pesan antrean atau job background), simpan yang asli sebagai field parent sehingga cerita tetap terhubung.

Kekurangan umum lain adalah logging parsial. Tim menambahkan ID ke API pertama, tapi lupa di proses worker, job terjadwal, atau lapisan akses basis data. Hasilnya adalah jalan buntu: Anda melihat permintaan masuk sistem, tapi tidak tahu ke mana selanjutnya.

Hindari masalah "kekacauan penamaan"

Bahkan ketika ID ada di mana-mana, akan sulit dicari jika setiap layanan menggunakan nama field atau format berbeda. Pilih satu nama dan patuhi di frontend, API, dan log (mis. correlation_id). Juga pilih satu format (sering UUID), dan perlakukan case-sensitive agar copy-paste bekerja.

Jangan kehilangan ID saat sesuatu salah. Jika API mengembalikan 500 atau error validasi, sertakan ID korelasi di respons error (dan idealnya di header respons juga). Dengan begitu pengguna bisa menempelkannya ke chat dukungan, dan tim Anda bisa langsung menelusuri jalur lengkap.

Tes cepat: bisakah orang dukungan mulai dari satu ID dan mengikutinya melalui setiap baris log yang terlibat, termasuk gagal?

Daftar periksa cepat untuk memverifikasi cakupan end-to-end

Gunakan ini sebagai cek akal sehat sebelum Anda menyuruh dukungan untuk "cari saja di log." Ini hanya bekerja jika setiap hop mengikuti aturan yang sama.

Pemeriksaan wajib lulus

• Anda punya satu format ID dan satu nama header, digunakan di mana-mana (frontend, gateway, API, worker).
• Frontend membuat (atau menerima) ID pada awal aksi pengguna dan mempertahankannya sampai aksi selesai.
• Titik masuk API membuat ID jika hilang dan selalu mengembalikannya di header respons.
• Setiap layanan backend menyertakan correlation_id di log terkait permintaan sebagai field terstruktur.
• On-call bisa menempelkan satu ID ke pencarian log dan melihat jalur lengkap dalam beberapa menit: request edge, auth, panggilan layanan, operasi basis data, dan retry.

Jika ada pemeriksaan gagal, perbaiki seperti ini

Pilih perubahan terkecil yang membuat rantai tidak terputus.

• Jika ID berubah di tengah perjalanan, hentikan pembuatan ID baru di layanan internal. Pertahankan correlation_id asli dan tambahkan span_id terpisah jika butuh detail lebih.
• Jika log tidak memiliki field, tambahkan middleware logging sehingga engineer tidak perlu ingat memasukkannya.
• Jika dukungan tidak bisa mendapatkan ID, pastikan UI menampilkannya di layar error dan gateway memantulkannya kembali pada setiap respons.

Tes cepat yang menangkap celah: buka devtools, picu satu aksi, salin ID korelasi dari permintaan pertama, lalu konfirmasi Anda melihat nilai yang sama di setiap request API terkait dan setiap baris log yang sesuai.

Langkah berikutnya: masukkan ke proses rilis Anda

ID korelasi hanya membantu jika semua orang menggunakannya dengan cara yang sama, setiap saat. Perlakukan perilaku ID korelasi seperti bagian yang wajib dari pengiriman fitur, bukan sekadar tweak logging.

Tambahkan langkah jejak kecil ke definition of done untuk setiap endpoint atau aksi UI baru. Bahas bagaimana ID dibuat (atau digunakan kembali), di mana ia hidup selama alur, header apa yang membawanya, dan apa yang dilakukan setiap layanan saat header hilang.

Checklist ringan biasanya cukup:

• Frontend: buat atau gunakan kembali satu ID per aksi pengguna, dan lampirkan ke setiap panggilan API untuk aksi itu.
• Entry API: terima header, validasi atau buat, lalu pantulkan kembali di respons.
• Backend: teruskan ke layanan hilir dan job, serta sertakan di log.
• Logging: pertahankan nama field konsisten (mis. correlation_id) di seluruh aplikasi dan layanan.
• Review: tolak PR yang menambah endpoint tanpa tes yang membuktikan ID muncul di log.

Dukungan juga butuh skrip sederhana agar debugging cepat dan dapat diulang. Tentukan di mana ID muncul bagi pengguna (mis. tombol "Copy debug ID" pada dialog error), dan tuliskan apa dukungan harus minta dan di mana mencari.

Sebelum mengandalkannya di produksi, jalankan flow berlapis yang meniru penggunaan nyata: klik tombol, picu error validasi, lalu selesaikan aksi. Konfirmasi Anda bisa mengikuti ID yang sama dari permintaan browser, lewat log API, ke worker latar, dan hingga log panggilan basis data jika Anda merekamnya.

Jika Anda membangun aplikasi di Koder.ai, akan membantu menuliskan header ID korelasi dan konvensi logging Anda ke dalam Planning Mode sehingga frontend React dan layanan Go yang digenerate mulai konsisten secara default.