Request ID Laravel: Menghubungkan Satu Request ke Log dengan Context

Ketika satu request menghasilkan beberapa baris log, masalahnya sering bukan karena log tidak ditulis. Masalahnya adalah sulit menentukan baris mana yang berasal dari eksekusi request yang sama. Sebuah identifier yang konsisten dapat membantu mempersempit pencarian: cari nilainya, lalu baca rangkaian log yang membawanya.

Di Laravel 13.x, salah satu alur yang terdokumentasi adalah menambahkan metadata ke Context. Metadata tersebut ikut tersedia pada log yang ditulis selama request. Jika request kemudian mengirim job ke queue, informasi context yang didukung alur Laravel dapat dibawa ke job dan dipulihkan ketika job dijalankan. Artikel ini memakai Context sebagai jalur utama agar satu konsep tetap utuh: buat atau terima satu ID, simpan di context, tulis log, lalu pahami batas ketika eksekusi berpindah ke job.

Contoh di sini berbasis dokumentasi dan belum dijalankan pada proyek Laravel. Middleware hanya dipakai sebagai lokasi penempatan contoh; pembuatan dan registrasi middleware bukan topik artikel ini.

Apa yang sebenarnya dibantu oleh request ID?

Request ID adalah nilai yang dipakai sebagai metadata bersama untuk membedakan satu alur request dari alur lain. Misalnya, seorang pengguna melaporkan bahwa proses checkout gagal. Tanpa identifier, pencarian berdasarkan waktu atau pesan log dapat bercampur dengan request pengguna lain. Dengan request_id, setiap baris yang relevan dapat dicari menggunakan nilai yang sama.

Contoh ini tidak membuat sistem menjadi penuh observability. Context correlation bukan dashboard, alerting, retention policy, distributed tracing, atau bukti bahwa semua komponen telah terpantau. Ia hanya memberi metadata yang membantu menghubungkan catatan pada alur yang memang membawa metadata tersebut.

Nilai yang dipilih juga bukan otomatis aman untuk dicatat. Jangan memasukkan password, token, secret, seluruh payload request, atau PII yang tidak diperlukan ke dalam context. Identifier yang dipakai tetap perlu melewati peninjauan klasifikasi data di proyek Anda.

Pilih satu tempat untuk menambahkan context

Laravel mendokumentasikan Context facade untuk menangkap dan membagikan informasi sepanjang request, job, dan command. Informasi yang ditambahkan ke context juga otomatis disertakan sebagai metadata pada log aplikasi.

Satu ilustrasi ringkasnya seperti berikut:

<?php

namespace App\Http\Middleware;

use Closure;
use Illuminate\Http\Request;
use Illuminate\Support\Facades\Context;
use Illuminate\Support\Str;
use Symfony\Component\HttpFoundation\Response;

class AddRequestContext
{
    /**
     * Handle an incoming request.
     */
    public function handle(Request $request, Closure $next): Response
    {
        Context::add([
            'request_id' => Str::uuid()->toString(),
        ]);

        return $next($request);
    }
}

Ada tiga keputusan penting dalam fragmen tersebut:

1. Str::uuid()->toString() membuat nilai identifier untuk contoh ini.
2. Context::add menyimpan nilai dengan key request_id pada context saat ini.
3. $next($request) meneruskan request; baris ini menunjukkan batas penempatan context, bukan tutorial middleware.

Kode tersebut tidak membuktikan bahwa ID sudah benar-benar dibuat pada aplikasi Anda. Nama class, cara middleware dipasang, dan aturan apakah client boleh menerima ID harus disesuaikan dengan desain proyek. Jika aplikasi sudah memiliki request identifier dari gateway atau lapisan lain, pertimbangkan apakah nilai itu yang perlu diteruskan, bukan membuat identifier kedua tanpa alasan.

Dua API lain yang berdekatan adalah Log::withContext dan Log::shareContext. Dokumentasi logging menjelaskan keduanya untuk menambahkan context pada log. Artikel ini memilih Context sebagai alur utama karena dokumentasi Context juga menjelaskan bagaimana data tersebut tersedia melintasi request, job, dan command. Jangan membaca pilihan ini sebagai larangan memakai withContext atau shareContext; pilihan API perlu mengikuti batas alur dan versi aplikasi.

Tulis log tanpa mengulang identifier di setiap baris

Setelah context berisi identifier, kode aplikasi dapat menulis log biasa melalui Log. Metadata dari context akan menyertai log yang ditulis dalam alur tersebut.

use Illuminate\Support\Facades\Log;

Log::info('Checkout mulai diproses.', [
    'order_id' => $order->id,
]);

Log::warning('Pembayaran belum mendapatkan respons.', [
    'order_id' => $order->id,
]);

Secara konseptual, kedua entry tetap memiliki field lokal seperti order_id, dan juga metadata context seperti request_id. Ini berbeda dari menambahkan request_id secara manual ke setiap pemanggilan Log. Context membantu mengurangi pengulangan pada alur yang sama, tetapi tidak menghapus kebutuhan untuk memilih informasi lokal yang relevan pada setiap pesan.

Ada juga perbedaan antara metadata context dan data yang hanya berlaku untuk satu log. order_id pada contoh di atas diteruskan pada pemanggilan tertentu. request_id dibagikan melalui context. Pemisahan ini membuat pembaca log dapat membedakan identitas alur dari detail peristiwa tertentu.

Pertimbangkan scope dan data yang dibagikan

Context::add dapat menambahkan satu nilai atau beberapa nilai sekaligus. Nilai yang ditambahkan dengan key sama dapat menggantikan nilai sebelumnya. Karena itu, tetapkan aturan sederhana: siapa yang boleh menetapkan request_id, kapan nilainya boleh berubah, dan apakah perubahan itu memang diinginkan.

Untuk data yang hanya diperlukan sementara dalam sebuah callback, Laravel juga mendokumentasikan scoped context. Context dapat dikembalikan ke keadaan semula setelah callback selesai. Detail seperti ini berguna ketika beberapa operasi yang lebih kecil berjalan dalam satu request, tetapi tidak diperlukan untuk alur request ID paling sederhana.

Laravel juga memiliki hidden context. Data hidden dapat dibaca oleh kode aplikasi tetapi tidak ditulis sebagai metadata log. Fitur ini bukan alasan untuk menyimpan secret tanpa kebijakan; tetap perlakukan semua context sebagai data yang perlu diklasifikasikan. Hidden context juga tidak mengubah kebutuhan untuk membatasi payload yang dibawa ke job.

Jika request mengirim job ke queue

Context menjadi lebih berguna ketika satu request mengirim pekerjaan lanjutan. Dokumentasi Laravel menjelaskan bahwa informasi yang ada pada context ketika job di-dispatch dapat ditangkap bersama job. Saat job mulai dijalankan, informasi tersebut dipulihkan ke context yang sedang aktif.

Alur konseptualnya:

1. Request menambahkan request_id ke Context.
2. Request menulis log dan mengirim sebuah job.
3. Laravel menangkap informasi context yang dibagikan ketika job di-dispatch.
4. Saat job dieksekusi, context tersebut di-hydrate kembali.
5. Log dari job dapat membawa metadata correlation yang berasal dari request awal.

Contoh job berikut hanya menunjukkan titik log-nya:

<?php

namespace App\Jobs;

use Illuminate\Contracts\Queue\ShouldQueue;
use Illuminate\Support\Facades\Log;

class ProcessCheckout implements ShouldQueue
{
    public function handle(): void
    {
        Log::info('Checkout diproses oleh job.');
    }
}

Contoh ini tidak mengajarkan dispatch, worker, retry, timeout, atau penanganan kegagalan queue. Artikel tentang lifecycle queue memiliki batas yang berbeda. Yang perlu dipahami di sini hanya hubungan metadata: jika context memang dibagikan melalui alur yang didokumentasikan, log job dapat dibaca sebagai kelanjutan correlation dari request yang mengirimnya.

Jangan menganggap semua proses di luar alur tersebut otomatis membawa ID. Command yang dijalankan terpisah, request yang tidak melewati titik penambahan context, sistem lain, dan integrasi pihak ketiga memerlukan desain serta verifikasi tersendiri. Bahkan pada job, metadata correlation bukan jaminan bahwa setiap baris dari seluruh sistem akan memiliki ID yang sama.

request_id bukan pengganti log yang jelas

Identifier membantu pencarian, tetapi pesan log tetap perlu menjelaskan peristiwa. Bandingkan dua kebiasaan berikut:

• Menulis pesan Gagal dengan identifier saja.
• Menulis Checkout gagal saat menunggu respons pembayaran dengan order_id yang memang diperlukan dan context request_id.

Pilihan kedua lebih berguna karena identifier menghubungkan alur, sedangkan pesan dan field lokal menjelaskan apa yang terjadi. Context bukan pengganti level log, pesan yang spesifik, atau data domain yang relevan.

Jaga pula batas antara correlation dan security. Memiliki UUID di log tidak membuktikan bahwa request telah terautentikasi, bahwa akses sudah diotorisasi, atau bahwa data pada log aman untuk semua pembaca. Peninjauan redaksi dan klasifikasi data tetap menjadi tanggung jawab aplikasi dan organisasi.

Kapan memilih Context dan kapan memakai log context?

Gunakan Context sebagai pilihan yang masuk akal ketika metadata perlu dipahami sebagai bagian dari alur eksekusi yang dapat melintasi request, job, atau command, dan Anda ingin memanfaatkan perilaku propagation yang didokumentasikan Laravel.

Log::withContext atau Log::shareContext dapat lebih sesuai ketika kebutuhan Anda memang terbatas pada penambahan context ke logging dalam lingkup tertentu. Bedakan kebutuhan tersebut dari kebutuhan membawa data melewati boundary job. Jangan memilih API hanya berdasarkan nama “trace ID”; periksa alur, lifecycle, dan perilaku versi Laravel yang digunakan.

Aturan praktisnya: pilih satu API sebagai jalur utama, tetapkan satu key identifier, batasi data yang dimasukkan, lalu periksa log pada alur yang benar-benar dijalankan. Jangan menulis bahwa correlation sudah terbukti hanya karena kode terlihat mirip dengan dokumentasi.