Skip to content

Error tracking

Error tracking is on by default (errors.enabled = true), but it captures nothing until you wire Ranetrace into Laravel's exception handler. That one line is required.

Register the exception handler

In bootstrap/app.php, call Ranetrace::handles() inside ->withExceptions():

use Illuminate\Foundation\Configuration\Exceptions;
use Ranetrace\Laravel\Facades\Ranetrace;

->withExceptions(function (Exceptions $exceptions) {
    Ranetrace::handles($exceptions);
})

Without this wiring, unhandled exceptions are not captured (though Ranetrace::report($exception) still works for in-flow calls). handles() preserves Laravel's own default logging. Once it is in place, anything that flows through Laravel's report(), including unhandled exceptions Laravel catches, reaches Ranetrace::report($exception) and is sent to Ranetrace after the worker runs.

What gets sent

From Ranetrace\Laravel\Ranetrace::report():

  • HTTP context (when not running in console): full URL, HTTP method, and headers. Sensitive headers are masked: cookie, authorization, x-csrf-token, x-xsrf-token.
  • Console context (when running in console): the command line invocation and argv.
  • Code context: up to 11 lines from the file where the exception occurred (5 before and 5 after), for files under 1 MB.
  • Stack trace.
  • Authenticated user (if any).
  • PHP version and Laravel version.

Reporting manually

use Ranetrace\Laravel\Facades\Ranetrace;

Ranetrace::report($exception);

report() takes a single Throwable argument: there is no second context parameter.

You can also call Laravel's built-in report() helper; it routes through the same handler:

try {
    $this->thirdPartyApi->sync();
} catch (Throwable $exception) {
    report($exception);
}

Testing your setup

php artisan ranetrace:test-errors

When you get notified

Ranetrace groups every report with the same exception class, file, line and environment into one error, and each report in that group is an occurrence. An error notifies you:

  • on its first occurrence, so a new error never goes unseen
  • on its 5th and 10th occurrence, which tell a one-off from a pattern
  • when it starts happening 10 times within an hour after a calmer hour, however old the error is
  • when it comes back after you resolved it, even if it happens only once

An error that keeps failing at a steady rate notifies once when the burst starts, not every hour. It notifies again only after it has been quiet for an hour and then bursts again. A snoozed error stays silent until the snooze ends, and an ignored error is not recorded at all.

The same error with the same message is recorded at most once every 5 minutes, so the occurrence count measures how often an error comes back, not every single request it failed. It also means a burst of 10 within an hour takes about 45 minutes of steady failure.

Notifications land in your inbox and on the channels you connected. Turn error notifications off or on under Notify, Rules.

Configuration

From config/ranetrace.php:

'errors' => [
    'enabled' => env('RANETRACE_ERRORS_ENABLED', true),
    'queue' => env('RANETRACE_ERRORS_QUEUE', true),
    'queue_name' => env('RANETRACE_ERRORS_QUEUE_NAME', 'default'),
    'timeout' => env('RANETRACE_ERRORS_TIMEOUT', 10),
],

To disable without uninstalling:

RANETRACE_ERRORS_ENABLED=false

On this page