d076/laravel-tracing

Tracing module for laravel

v0.3.1 2026-06-11 12:40 UTC

Requires

• php: ^8.3
• ext-json: *
• illuminate/bus: ^11.0|^12.0|^13.0
• illuminate/console: ^11.0|^12.0|^13.0
• illuminate/contracts: ^11.0|^12.0|^13.0
• illuminate/database: ^11.0|^12.0|^13.0
• illuminate/http: ^11.0|^12.0|^13.0
• illuminate/queue: ^11.0|^12.0|^13.0
• illuminate/routing: ^11.0|^12.0|^13.0
• illuminate/support: ^11.0|^12.0|^13.0

Requires (Dev)

• larastan/larastan: ^3.9
• orchestra/testbench: ^9.0|^10.0|^11.0
• pestphp/pest: ^3.0
• phpbench/phpbench: ^1.6

MIT

• Dmitry Titov

• laravel
• tracing

Published on Packagist.org on 2026-06-11 12:43 UTC

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:

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