Request ID dan Correlation ID: Cara Melacak Error di Aplikasi Web yang Melibatkan Banyak Layanan

Error pada aplikasi web jarang berhenti di satu tempat. Pengguna mungkin hanya melihat pesan “Gagal memuat data”, tetapi di belakangnya ada permintaan dari browser, proses PHP, query MySQL, panggilan ke API eksternal, dan mungkin sebuah job yang berjalan di latar belakang. Tanpa cara untuk menghubungkan semua proses itu, log aplikasi mudah berubah menjadi tumpukan pesan yang sulit dibaca.

Di sinilah request ID dan correlation ID berguna. Keduanya adalah penanda unik yang ditempelkan pada proses atau rangkaian proses tertentu. Dengan penanda ini, developer bisa mengikuti perjalanan satu permintaan dari awal sampai selesai, bahkan ketika permintaan tersebut melewati beberapa komponen berbeda.

Apa bedanya request ID dan correlation ID?

Request ID biasanya mengidentifikasi satu permintaan HTTP. Misalnya, browser mengirim permintaan untuk membuka halaman profil, lalu server memberikan ID seperti req-8f31. Semua log yang berkaitan langsung dengan permintaan tersebut dapat menyertakan ID yang sama.

Correlation ID memiliki cakupan yang lebih luas. ID ini menghubungkan beberapa permintaan yang masih berasal dari satu aktivitas pengguna atau satu alur bisnis. Contohnya, proses checkout dapat melibatkan permintaan ke server utama, layanan pembayaran, layanan pengiriman, dan sistem email. Masing-masing layanan boleh memiliki request ID sendiri, tetapi semuanya membawa correlation ID yang sama.

Dalam aplikasi sederhana, satu ID mungkin sudah cukup. Namun, ketika aplikasi mulai menggunakan banyak API atau layanan terpisah, perbedaan ini menjadi penting. Request ID menjawab pertanyaan “permintaan ini yang mana?”, sedangkan correlation ID membantu menjawab “semua proses ini bagian dari aktivitas apa?”.

Mengapa log biasa sering tidak cukup?

Bayangkan ada lima pengguna yang melakukan checkout hampir bersamaan. Log server mungkin mencatat pesan seperti “Payment request failed”, “Order created”, atau “Timeout from shipping API”. Jika tidak ada penanda unik, developer harus menebak pesan mana yang berasal dari pengguna tertentu.

Masalahnya menjadi lebih rumit ketika beberapa proses berjalan secara paralel. Waktu pencatatan log tidak selalu mencerminkan urutan bisnis yang sebenarnya. Sebuah pesan dari API pembayaran bisa muncul setelah log dari proses lain, meskipun proses tersebut dimulai lebih dulu.

Request ID dan correlation ID tidak menghilangkan error. Fungsinya adalah membuat error tersebut terlihat dalam konteks. Developer dapat mencari semua log dengan ID yang sama, lalu melihat urutan proses, parameter penting, status respons, serta titik ketika alur mulai gagal.

Mulai dari pintu masuk aplikasi

Langkah pertama adalah membuat atau membaca ID dari header HTTP ketika permintaan masuk. Header yang sering digunakan adalah X-Request-ID atau Trace-ID. Jika client sudah mengirim ID, server dapat menggunakannya setelah melakukan validasi. Jika belum ada, server membuat ID baru.

Contoh sederhana menggunakan PHP:

<?php

$requestId = $_SERVER['HTTP_X_REQUEST_ID'] ?? bin2hex(random_bytes(16));

// Simpan di konteks aplikasi atau object request
$requestContext = [
    'request_id' => $requestId
];

header('X-Request-ID: ' . $requestId);

function logMessage(string $message, array $context = []): void
{
    global $requestContext;

    $entry = array_merge(
        $requestContext,
        $context,
        ['message' => $message, 'time' => date(DATE_ATOM)]
    );

    error_log(json_encode($entry));
}

Contoh tersebut masih sederhana, tetapi sudah menunjukkan prinsip penting: ID dibuat sekali di awal, dikembalikan kepada client, dan dipakai ulang pada setiap log dalam satu permintaan.

Dalam aplikasi produksi, sebaiknya jangan menerima nilai ID secara mentah tanpa pemeriksaan. Batasi panjangnya, gunakan karakter yang aman, dan hindari menyimpan data sensitif di dalam ID. ID seharusnya hanya menjadi penanda, bukan tempat menyisipkan informasi pengguna atau token rahasia.

Teruskan ID saat memanggil API lain

Kesalahan umum terjadi ketika request ID hanya dipakai di server utama, lalu hilang saat aplikasi memanggil service lain. Akibatnya, log PHP memiliki satu ID, sedangkan log service pembayaran tidak memiliki hubungan yang jelas.

Saat membuat permintaan keluar, teruskan correlation ID dan buat request ID baru jika diperlukan. Contohnya:

$headers = [
    'X-Correlation-ID: ' . $correlationId,
    'X-Request-ID: ' . bin2hex(random_bytes(16)),
    'Content-Type: application/json'
];

Dengan pola ini, setiap service dapat mencatat identitas permintaannya sendiri, tetapi masih bisa dikelompokkan berdasarkan correlation ID. Jika layanan pembayaran mengalami timeout, developer dapat mencari correlation ID tersebut di log aplikasi utama, layanan pembayaran, dan sistem notifikasi.

Jangan lupa sisi browser

Untuk aplikasi yang banyak menggunakan JavaScript, ID juga sebaiknya terlihat dari sisi browser. Ketika fetch atau XMLHttpRequest gagal, frontend dapat mencatat request ID dari header respons dan menampilkannya kepada pengguna sebagai kode referensi.

const response = await fetch('/api/orders', {
  headers: {
    'X-Correlation-ID': correlationId
  }
});

const requestId = response.headers.get('X-Request-ID');

if (!response.ok) {
  showError(`Permintaan gagal. Kode referensi: ${requestId}`);
}

Kode referensi ini lebih berguna daripada pesan “terjadi kesalahan”. Pengguna dapat mengirimkannya kepada tim dukungan, sementara developer bisa langsung mencari jejak yang sesuai tanpa meminta pengguna menjelaskan ulang seluruh langkah yang dilakukan.

Format log yang mudah dicari

Hindari log yang hanya berupa kalimat bebas seperti “database error”. Gunakan format terstruktur, misalnya JSON, agar mudah dicari oleh sistem pemantauan atau alat analisis log.

{
  "level": "error",
  "message": "Payment provider timeout",
  "request_id": "req-8f31",
  "correlation_id": "checkout-42c1",
  "route": "POST /api/orders",
  "user_id": 1842,
  "duration_ms": 3200,
  "provider_status": 504
}

Informasi seperti route, durasi, status respons, dan nama operasi biasanya cukup untuk membantu diagnosis. Namun, jangan mencatat password, API key, token sesi, nomor kartu, atau data pribadi yang tidak diperlukan. Log yang terlalu lengkap dapat menjadi risiko keamanan baru.

Apa artinya bagi kita?

Request ID dan correlation ID bukan hanya kebutuhan perusahaan besar. Website kecil yang memiliki pembayaran, integrasi WhatsApp, layanan email, atau beberapa endpoint API juga bisa mendapat manfaatnya. Semakin banyak bagian yang terlibat dalam satu proses, semakin penting kemampuan untuk mengikuti alurnya.

Yang perlu diingat, ID tidak menggantikan monitoring, pengujian, atau penanganan error yang baik. Ia hanya menyediakan benang merah. Jika log tidak memiliki waktu yang jelas, level error, dan informasi operasi, ID saja tetap belum cukup.

Yang bisa dilakukan sekarang

• Buat request ID pada middleware atau titik masuk utama aplikasi.
• Kembalikan request ID melalui header respons agar dapat dibaca browser atau tim dukungan.
• Gunakan correlation ID untuk proses bisnis yang melewati beberapa layanan.
• Teruskan ID ketika PHP memanggil API, queue worker, atau service internal.
• Gunakan log terstruktur dengan field yang konsisten.
• Pastikan rahasia dan data sensitif tidak ikut masuk ke log.
• Tambahkan kode referensi yang aman ditampilkan kepada pengguna ketika terjadi error.

Debugging yang baik bukan hanya soal menemukan baris kode yang salah. Kita juga perlu tahu perjalanan sebuah permintaan: masuk dari mana, diproses oleh siapa, berhenti di titik mana, dan mengapa. Dengan request ID dan correlation ID, pencarian tersebut berubah dari menebak-nebak menjadi penelusuran yang memiliki jejak.

– Rio Yotto @rioyotto