Laravel: Generate a unique request ID for each request and put it into logs

Hey guys,

Today I'll share with you a tip that will skyrocket your production debugging workflow 😎

We're going to generate a unique ID for each request, which we can use the request ID to search for every related log of the given request ID.

Thus, if any issue happens, we can try to find the request ID (or customers give us), and then jump immediately to the logs and do the surgery 👀.

Pretty handy, isn't it? 💪

Let's jump to the topic & the implementation.

Requirement

You'll need Laravel 11 because we are going to use the Context feature.

If you haven't learned about Context, visit this page of mine:

Laravel Context & how to use it in a maintainable way

Why Context?

Laravel's "context" capabilities enable you to capture, retrieve, and share information throughout requests, jobs, and commands executing within your application. This captured information is also included in logs written by your application, giving you deeper insight into the surrounding code execution history that occurred before a log entry was written and allowing you to trace execution flows throughout a distributed system.

Implementation

Create a middleware to generate/accept ID

We'll have 2 scenarios:

If there is a X-REQUEST-ID header with a valid ID, we'll continue to use that ID
- This will help trace ALL REQUESTS of a particular user's lifecycle.
- I'll use X-REQUEST-ID, you can use any key that you like 🥹.
If not, we'll generate a new unique ID

Let's hit the command to create a new middleware:

php artisan make:middleware UseRequestId

And the implementation:

<?php

namespace App\Http\Middleware;

use Illuminate\Support\Str;

class UseRequestId
{
    public function handle(Request $request, Closure $next): Response
    {
        // get existing id or generate new one
        $requestId = $request->header('X-REQUEST-ID')
            ?? (string) Str::ulid();

        // add to context
        Context::add('requestId', $requestId);

        return $next($request);
    }
}

Register the middleware

Since my application is an API service, I'll apply the middleware to the api group.

Open bootstrap/app.php and register it:

use App\Http\Middleware\UseRequestId;


->withMiddleware(function (Middleware $middleware) {
    $middleware->prependToGroup(UseRequestId::class);
})

Using prependToGroup to ensure this middleware will be resolved at the top (global => this middleware => other middleware of api group)

Add a route and try it out 🥰

Add a sample API

// api.php

Route::get('/ping', function () {
    Log::info('pong');

    return response()->json([]);
});

Open the log file to check (laravel.log for the basic driver or laravel-{date}.log for daily driver).

We should see something like:

[2024-04-28 13:22:59] local.INFO: Pong  {"requestId":"01HWJDZ12P3CE4JDY3912YSDEA"}

To ensure it will print the same request ID, you can try to log multiple times/multiple files in the same lifecycle. For example:

Log::info('ping');
// do something
Log::info('pong');
// do something more
Log::info('end');

Result:

[2024-04-28 13:26:35] local.INFO: ping  {"requestId":"01HWJE5MD8DQ24DBDN5R8TXK7K"}
[2024-04-28 13:26:35] local.INFO: pong  {"requestId":"01HWJE5MD8DQ24DBDN5R8TXK7K"}
[2024-04-28 13:26:35] local.INFO: end  {"requestId":"01HWJE5MD8DQ24DBDN5R8TXK7K"}

Context already covered & battle-tested from Laravel too 👀

Add the ID to the response

Last part, we need to send the ID to the API consumers, so they can send the same ID or for error reporting purposes.

We'll transform a bit of the middleware handle method:

/** @var \Illuminate\Http\Response $response */
$response = $next($request);

return $response->header('X-REQUEST-ID', $requestId);

When hitting the $next, Laravel will process everything and give us the FINAL RESPONSE (after Error/Exception too).

So we can add the ID into the header (or body if you want) 😉

Result

Now our requests are bound with request IDs. With means:

Easier for us to search for logs of a given ID 😎 Debugging is much faster & better now.
- If you use any logging platform, surely it can search wayyy faster than normal text search ❤️.
Customers/API consumers can know their "request ID", if it has any issue, they can extract the request ID and report the problem to us 👀
Additionally, you can record more data in the Context, e.g.:
- Logged In User ID
- URL
- Timezone
- etc

Conclusion

Well, happy coding & happy debugging guys.

Until the next blog post 😎. Thanks for reading!

Laravel: Generate a unique request ID for each request and put it into logs

Comments

Tech tips

Render HTML to PDF with RenderPDF.io

More from this blog

Fetch and compute first, write later

Mark as default - the optimal way

Almost 2026, but I still choose WordPress for CMS

Laravel Excel: How to append rows to an existing Excel file

Laravel Herd PRO reviews

Requirement

Why Context?

Implementation

Create a middleware to generate/accept ID

Register the middleware

Add a route and try it out 🥰

Add the ID to the response

Result

Conclusion

Command Palette

Comments

Tech tips

Render HTML to PDF with RenderPDF.io

More from this blog

Requirement

Why Context?

Implementation

Create a middleware to generate/accept ID

Register the middleware

Add a route and try it out 🥰

Add the ID to the response

Result

Conclusion