Download the PHP package ahmedhsieb/laravel-request-tracer without Composer

Request Tracer

Replace dd() with a trace of the whole request.

dd() shows one value in one place and kills the request. Request Tracer records the whole request, step by step, and lets you open any step: what went in, what came out, which lines ran, which rows were written.

• Production

Install

That is all. No config file, no migration, nothing to publish: the tables create themselves and the dashboard is served from the package.

Want to look around first? npm ci && npm run dev in the package folder opens the dashboard with demo data, no backend needed.

Start tracing

Use your application as usual, then open /request-tracer.

It works like queue:work: while it runs, everything the project does is traced (requests, queued jobs, artisan commands, scheduled tasks) and each trace is printed in the terminal. Press Ctrl+C and it stops. When it is not running nothing is recorded, and the package costs 25 to 65 µs per request.

• Local: the dashboard is open to everyone.
• Any other environment: closed (403) until you define who may open it, see Production.

Features

The flow: everything the request did

Middleware, controller, validation, services, queries, HTTP calls, events, jobs, cache, logs and exceptions, each on a timeline with its real start and duration. Above it: time, memory, queries, problems, tables written, and where the time went by kind of step. The strip under the tabs is a time map: drag over it to zoom the timeline into that part of the request.

Hover a step to preview it, click to pin it. The right side shows its Input and Output, printed like dd(), with secrets masked.

Folders: deep requests stay readable

A step with steps inside is a folder. The list shows one folder at a time, so names are never squeezed by indentation, however deep the request goes. Open a folder with the button on its row, go up with the arrow, or jump to any level from the path above the list. The time axis follows: an open folder shows its own stretch of time.

Search and filters, inside the folder

Search by name, SQL, file or summary. Filter by kind (query, HTTP, cache...), speed (slow / fast) and result (failed / OK). They look at everything below the open folder, however deep, and list the matches with the path each one is in. A switch narrows them to the folder's own steps.

Graph view

The same steps as columns that grow to the right. Click a step and what is inside it opens in the next column; the path you came by stays on the left, and clicking an earlier step goes back. Lines are as thick as the share of the time a step took.

Inside the code, line by line

Every condition, block and variable of a step: which if was true, which block never ran, what the variables held. Hover a line to see what happened there, click it to keep the pop-up open. Replay walks through the lines in the order they ran. Functions the step called appear under the line that calls them.

Database: what the request wrote

Every table the request changed: INSERT, UPDATE, DELETE, the rows, and for updates before → after with the changed cells highlighted. Each card names the step that wrote it and whether the transaction committed or rolled back.

Problems: found for you

Uncaught and caught exceptions, N+1 queries, repeated and slow queries, slow steps and failed HTTP calls, each with an explanation, the file and line, and a link to the step in the flow.

Replay: run a request again, traced

Nothing was recording when it happened? Run it again. In the dashboard press Replay a request, paste a cURL command (browser: Network tab, Copy as cURL) or describe the request. You choose what it may change:

Replay is off in the production environment unless you turn it on; running for real there needs a second switch.

Journal: when you do not know which request it was

Turn it on (REQUEST_TRACER_JOURNAL=true) and every request leaves one light row (URL, masked body, user, status, error), traced or not, for an hour. Pick the one that failed and it replays itself with a full trace. Group by route puts the requests of one route prefix together in the list and in the journal.

Also in the dashboard

• Ctrl+K: search requests, the steps of the open request, and actions, from the keyboard.
• Record from outside: a signed header for one request, or watch a user for a while, for servers where you cannot run the listen command.
• Jobs and commands: a job started by a request links back to it, and the other way round.
• Dark and light themes; panes you can resize; works on a narrow screen.

Configure

There is nothing to configure to start. To change something publish the file and keep only the keys you change (every key has a default):

The keys you will reach for first:

Environment variables: REQUEST_TRACER_ENABLED, REQUEST_TRACER_MODE, REQUEST_TRACER_JOURNAL, REQUEST_TRACER_DB_CONNECTION. Every key is in docs/04-configuration.md.

Commands

Examples

Run a failed request again, with a full trace

Replay a request as a user, sending a body

Run it for real, then undo it

Trace one request on a server, without the listen command

Trace something outside app/, or leave a class out

Show the tenant or module next to each request

In production

Same two steps, on the server. The dashboard stays closed until you say who may open it:

• Secrets are masked before they are stored, by field name and by shape (Bearer ...). The raw value never reaches the database. The one exception is the encrypted, short-lived undo log of a real replay.
• A failure inside the tracer never breaks a request; it is logged and swallowed.
• Nothing records on its own: only while request-tracer:listen runs, or for a signed header, a watched user, a sample, or a replay.
• To trace without the command: signed header, watched user, sampling.

What it costs

Nothing measurable when nobody listens. While listening, a request of 47 steps and 15 queries takes about 5 ms longer with input and output for every call, about 7.5 ms with every line as well, and 7 to 10 ms more after the response was sent. Method and caveats in docs/benchmarks.md.

Honest limits

Proxies cannot see new, final classes, private or static methods. Line-by-line tracing compiles a copy of each file of code.paths the first time it is loaded while somebody listens; a long-running worker (Octane, queue:work) keeps what it loaded before you started listening until it restarts. Masking is name based. The package is 0.x. More in How it compares.

Documentation

Changelog

License

MIT.

See README.ar.md