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

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 of secret body fields — password, password_confirmation, current_password, secret, token, access_token, refresh_token, api_token, api_key, client_secret, private_key — on the inbound request, the response, and both halves of an outbound call. Names are matched exactly, not as substrings, so a field of your own (stripe_token, otp) has to be added to the list;
masking of secret headers, a separate list matched case-insensitively: authorization, cookie, x-api-key, x-csrf-token, x-xsrf-token, php-auth-pw inbound, set-cookie on responses;
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:

Variable	Default	Purpose
`TRACING_ENABLED`	`true`	Record inbound requests
`TRACING_OUTGOING_ENABLED`	`true`	Record outbound requests
`TRACING_DRIVER`	`database`	`database` (sync) or `queue` (async via Horizon)
`TRACING_UI_ENABLED`	`true`	Web UI
`TRACING_RETENTION_DAYS`	`30`	Retention in days; cleaned via `php artisan model:prune`

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):

Mode	Overhead per request
Baseline (tracing disabled)	—
`TRACING_DRIVER=database`	~+0.17 ms
`TRACING_DRIVER=database` + `TRACING_STORE_RESPONSE_BODY=true`	~+0.21 ms
`TRACING_DRIVER=queue` (sync driver, worst case)	~+0.31 ms

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

d076 / laravel-tracing

Maintainers

Package info

Statistics

Security