Download the PHP package kolaybi/request-tracer without Composer

Request Tracer

Standalone request tracing package for Laravel. Captures outgoing HTTP and SOAP requests, and optionally incoming requests. All traces are stored asynchronously via queued jobs.

Requirements

• PHP 8.4+
• Laravel 12+
• ext-soap and ext-simplexml (only if using SOAP tracing)

Installation

Publish the config:

Configuration

If REQUEST_TRACER_MASK_SENSITIVE=true, matching keys in headers and JSON/form payloads are masked before storage.

Middleware

Add RequestTracerMiddleware to your middleware stack. It generates a trace_id for every request and records incoming traces when enabled.

The middleware accepts an optional channel parameter to tag incoming traces by route group:

Context Provider

Implement TraceContextProvider to supply tenant, user, and server information:

Register it in your config:

Usage

HTTP Tracing

Outgoing HTTP requests are traced automatically when outgoing.enabled is true. Use channel() or traceOf() to tag requests:

channel() and traceOf() also accept an enum. Backed enums resolve to their value, pure enums to the case name:

SOAP Tracing

Extend TracingSoapClient for traced SOAP calls:

TracingSoapClient supports lazy initialization — set the WSDL later if needed:

Incoming Tracing

Enable in config:

The middleware records every incoming request with method, path, route, status, timing, headers, and optionally the response body.

Note: response_size is always recorded regardless of the capture_response_body setting. It is read from the Symfony Response content when available, and falls back to the Content-Length header when content is unavailable.

Debugging

Display a chronological waterfall of all traces linked to a trace_id:

The command first prints a summary header:

Followed by a waterfall table of all traces sorted by start time:

This is useful for inspecting the full request flow — incoming request plus all outgoing calls it triggered — in chronological order.

Inspect

Drill into a single trace by its ULID with progressive verbosity:

The command searches both incoming and outgoing tables automatically — no need to specify which.

Data Retention

Table Rotation (recommended)

Rotate trace tables daily — the current table is atomically swapped with a fresh empty one, and the old data moves to a dated archive table (e.g. outgoing_request_traces_20260309). Archives older than retention_days are dropped automatically.

Schedule it to run daily:

Row-level Purge

Alternatively, delete old rows from the current table in chunks:

Or set retention_days in config and schedule it:

Preserving Selected Traces

Some traces are operationally critical (e.g. integrations with external systems for audit purposes) and must survive rotation and retention. The request-tracer:preserve command sweeps rows matching configured glob patterns from the just-rotated archive table into a permanent *_persistent table.

Configure persist patterns per direction:

• Incoming patterns match request->path() (same as INCOMING_ONLY).
• Outgoing patterns match the trimmed host + path string (same as OUTGOING_ONLY).

Wire the command to run immediately after rotation:

Backfill or re-run a specific archive:

The command is idempotent: re-running over the same archive does not duplicate rows (uses INSERT IGNORE / ON CONFLICT DO NOTHING keyed on the ULID PK).

How It Works

Outgoing Traces

• RequestSending listener stores per-request trace metadata (started_at) in request attributes and RequestTimingStore
• Http::channel() / Http::traceOf() and Http::withTraceExtra() set per-request metadata in request_tracer attributes
• Event listeners (ResponseReceived, ConnectionFailed) build trace attributes and dispatch StoreTraceJob
• Any X-Trace-* headers present on requests/responses are stripped before persisting

Incoming Traces

• RequestTracerMiddleware generates a trace_id and records start time
• After the response is returned, IncomingTraceRecorder builds attributes and dispatches StoreTraceJob
• The same trace_id links incoming and outgoing traces within a request

SOAP Traces

• TracingSoapClient stores channel/extra as instance properties
• __doRequest() dispatches events with timing, channel, and extra
• Properties are reset after each call (no leakage between calls)

Workers / Queue Jobs

• The middleware does not run on workers, but outgoing tracing works identically
• trace_id is lazily generated via Context on the first outgoing call
• Laravel resets Context between queue jobs, so each job gets a fresh trace_id

Changelog

Please see CHANGELOG for more information on what has changed recently.

Contributing

Please see CONTRIBUTING for details.

License

Please see License File for more information.