README

A Laravel package for tracing inbound and outbound HTTP requests. Each inbound request gets a unique X-Trace-Id (UUID7); every outbound request made via the Http facade, plus any jobs and events dispatched from that request, automatically inherit the same trace_id.

Optionally ships a web UI at /tracing for browsing recorded requests.

Requirements

• PHP 8.3+
• Laravel 11 / 12 / 13
• Database: PostgreSQL / MySQL / SQLite

Installation

composer require d076/laravel-tracing

Register the service provider in bootstrap/providers.php:

return [
    App\Providers\AppServiceProvider::class,
    D076\Tracing\Providers\TracingServiceProvider::class,
];

Run migrations:

php artisan migrate

Publish the config (optional):

php artisan vendor:publish --tag=tracing-config

Quick start

Works out of the box with sensible defaults:

• synchronous recording of inbound and outbound requests to the database;
• masking for common secrets (password, token, authorization, access_token, etc.);
• X-Trace-Id header on every response;
• UI at /tracing, accessible only in the local environment by default;
• API rate limit of 120 req/min.

Key switches:

See docs/configuration.md for the full reference.

UI authorization

By default /tracing is accessible only in the local environment. In production, override the gate in AppServiceProvider::boot():

use Illuminate\Support\Facades\Gate;

Gate::define('viewTracing', fn ($user) => $user?->isAdmin() ?? false);

Using trace_id in your code

use D076\Tracing\Context\TraceId;

Log::info('processing order', ['trace_id' => app(TraceId::class)->get()]);

Queued jobs require no setup — trace_id is automatically inherited from the parent HTTP request (see docs/configuration.md → trace_id propagation to jobs).

Performance overhead

Measured with phpbench on a minimal testbench app, SQLite in-memory, no opcache (Docker, PHP 8.4):

With a real async queue (Redis + Horizon), the main-request overhead for TRACING_DRIVER=queue drops to near zero — only job dispatch cost, while the actual DB write happens in the worker.

Use TRACING_DRIVER=queue if latency matters; use a separate database connection if I/O isolation matters.

Documentation

• Architecture — package components, lifecycle of inbound and outbound requests.
• Configuration — full env reference, masking, rate limiting, async mode, route exclusions, trace_id propagation to jobs, UI authorization.
• Database — what is stored, table schemas, example SQL queries.

License

MIT