Logs and debugging

The kit writes a daily log, throttles repeated exceptions so one broken page does not fill it, and can post each new error to Slack. In development it adds the debugbar, an N+1 query detector and a live tail of the log. This guide covers the variables behind each and the two things to do before deploying: protect the log viewer and set the Slack token.

The log viewer at /logs

routes/web.php registers GET /logs with the LogViewerController of the rap2hpoutre/laravel-log-viewer package. It lists the files in storage/logs/, lets you read, download and delete them, and the kit adds no middleware to it: the route is public. Protect it before deploying, either by wrapping it:

Route::get('logs', LogViewerController::class . '@index')->middleware(['auth', 'role:admin']);

or by moving the line to routes/admin.php, where it becomes /admin/logs behind the admin role.

Channels and variables

config/logging.php keeps Laravel's channels plus one of the kit's, slack_api.

The stock slack channel is a plain Laravel channel: nothing in the kit writes to it unless you add it to LOG_STACK. The kit's error alerts go through slack_api.

Error alerts in Slack

slack_api is a Monolog SlackHandler that talks to the Slack API with a bot token. It posts as Laravel Logs with the :boom: icon, at level error and above, as an attachment that includes the context of the exception except the exception object, the URL and the user id.

To turn it on:

1. Create a Slack app with a bot token that has chat:write, and invite the bot to the channel.
2. Set the variables:

SLACK_BOT_TOKEN=xoxb-your-token
SLACK_LOG_CHANNEL=#errors

Nothing else changes: the exception handler in bootstrap/app.php checks whether slack_api has a token and, when it does, posts every exception that passes the throttle below. A database connection refused, SQLSTATE[HY000] [2002], never reaches Slack even then, because it is noise the next request fixes. Livewire's Cannot update locked property depends on who sent it: with nobody signed in, it is discarded before it is reported, so it reaches neither the log nor Slack; with a session, it is reported like any other exception, Slack included.

In the local environment none of this runs: the handler writes the exception to the log and stops before the Slack check, so nothing reaches Slack on your machine, token or not. To see an alert arrive, try it in an environment other than local.

How often an exception is reported

bootstrap/app.php decides, in withExceptions, whether an exception is written at all. In the local environment every exception is reported, every time. Elsewhere:

• The message is normalised, replacing numbers and timestamps with placeholders, and hashed with the class name. The count for that signature is kept in the cache for 30 days.
• The exception is reported when the count reaches 1, 10, 25, 50, 100, 300, 500 or 1000, then every 1000 after that.
• Even at those counts, the same signature is reported at most once every 5 minutes.
• Messages listed in ignoredExceptionMessages(), today only the modal package's activeComponent must not be accessed before initialization, are not reported in any environment.

Every report carries extra context: the last non-Livewire URL the person opened, the request path, the user agent, the environment, the Livewire component that was running and how many times this exception has been seen. That is the count the Clear log cache button in The devzone resets, when the cache store is database, so a fixed error is reported again from 1.

The N+1 query detector

beyondcode/laravel-query-detector watches every request and reports a relation loaded in a loop. config/querydetector.php:

Its output is the debugbar: the findings appear in a Messages tab of the bar. Whitelist a relation that is loaded on purpose in the except array of the config, with both the model class and the relation name:

'except' => [
    App\Models\Order::class => [
        App\Models\OrderLine::class,
        'lines',
    ],
],

The debugbar

barryvdh/laravel-debugbar is a dev dependency; it shows queries, views, the session and the request timeline at the bottom of every page. config/debugbar.php:

Never enable it in production: it exposes queries and session data to anyone who loads a page.

Tail the log while developing

composer dev starts the server, the queue worker, Vite and php artisan pail, which prints every log entry in the terminal as it happens. Run php artisan pail on its own to follow the log of a running site, and php artisan pail --filter="QueryException" to see one kind of entry. On a server, follow the daily file instead:

tail -f storage/logs/laravel-$(date +%F).log

The variables to set on a server, these among them, are listed in Deploy your project.