Laravel Error Tracking with the Sentry SDK

Laravel's exception handler is your safety net — but only if you know when it catches something. By default, errors log to files or get emailed, and you discover critical bugs hours or days later. Laravel error tracking connects your app's exceptions directly to a dashboard where you can see what broke, who it affected, and a complete stack trace ready for fixing.

This guide sets up production-grade error tracking in Laravel using the Sentry SDK, pointed at LightTrace. You'll capture exceptions across HTTP requests, queue jobs, and artisan commands, with full context attached so you can diagnose issues in minutes instead of hours. If you're new to error tracking, our what is error tracking guide explains the core concepts — capture, context, grouping, and alerting — and why every app needs it.

Install and initialize the SDK

Add the Sentry PHP SDK using Composer:

composer require sentry/sentry-laravel

Laravel's service provider auto-discovery will register the SDK. To initialize it, create or update your .env with your LightTrace DSN:

SENTRY_LARAVEL_DSN=https://<key>@your-lighttrace-host/1
SENTRY_ENVIRONMENT=production
SENTRY_RELEASE=app@1.0.0

Then add the service provider to config/app.php if not auto-discovered:

'providers' => [
    // ...
    Sentry\Laravel\ServiceProvider::class,
],

That's it. From this point on, any uncaught exception in your Laravel app — a database error, a validation failure, a network timeout — is automatically captured and sent to LightTrace.

Hook into Laravel's exception handler

For finer control, you can integrate the SDK directly into Laravel's exception handler. Open app/Exceptions/Handler.php and use the SDK in the report method:

<?php

namespace App\Exceptions;

use Illuminate\Foundation\Exceptions\Handler as ExceptionHandler;
use Sentry\Laravel\Integration;

class Handler extends ExceptionHandler
{
    public function report(\Throwable $exception)
    {
        if (app()->bound('sentry')) {
            Integration::captureException($exception);
        }

        parent::report($exception);
    }
}

This lets you apply custom logic before reporting — you can filter certain exceptions, add extra context, or throttle high-volume errors. The SDK still sends them automatically, so you're not duplicating work; you're just gaining control.

Add request context and user tracking

Raw stack traces are a starting point, but the real speed-up comes from context. You want to know which user hit the error, what request triggered it, and what led up to it. The SDK captures HTTP context automatically (URL, method, headers), but you should set the user and add breadcrumbs at meaningful moments. This pattern works across all frameworks — Rails, Django, and Node.js all benefit from rich context — because it's what actually makes errors solvable:

<?php

use Sentry\State\Scope;

// In a middleware or controller, after authentication:
\Sentry\configureScope(function (Scope $scope): void {
    $scope->setUser([
        'id' => auth()->id(),
        'email' => auth()->user()->email ?? null,
        'username' => auth()->user()->name ?? null,
    ]);
});

// Add a breadcrumb when something interesting happens:
\Sentry\addBreadcrumb(
    new \Sentry\Breadcrumb(
        \Sentry\Breadcrumb::LEVEL_INFO,
        \Sentry\Breadcrumb::TYPE_USER_INTERACTION,
        'payment',
        'Initiated payment processing',
        ['order_id' => $order->id, 'amount' => $order->total]
    )
);

Now every error that occurs carries the breadcrumb trail that led to it. You can reproduce the exact sequence of events instead of guessing why the exception happened.

Track errors in queue jobs and commands

Laravel's queues and Artisan commands run outside the HTTP lifecycle, so context is different — there's no $_SERVER or request object. The SDK handles this automatically, but you should still add job-specific context:

<?php

namespace App\Jobs;

use Illuminate\Bus\Queueable;
use Illuminate\Contracts\Queue\ShouldQueue;
use Illuminate\Foundation\Bus\Dispatchable;

class ProcessPayment implements ShouldQueue
{
    use Dispatchable, Queueable;

    public function handle()
    {
        \Sentry\configureScope(function ($scope) {
            $scope->setTag('job', 'ProcessPayment');
            $scope->setContext('order', ['id' => $this->orderId]);
        });

        // Your job logic here
    }
}

The same pattern works for Artisan commands — tag them so you can spot which command threw an error, and add context about what it was processing. This turns background job failures from silent ghosts into grouped, actionable issues.

Sample rates and error grouping

In high-traffic Laravel apps, you'll get a lot of errors — some of which are harmless (a 404, a validation error). The SDK ships with sensible defaults: it captures all errors, but you can sample transactions (traces of slow requests) to avoid overwhelming the system.

// config/app.php or bootstrap/app.php:
\Sentry\init([
    'dsn' => env('SENTRY_LARAVEL_DSN'),
    'environment' => env('SENTRY_ENVIRONMENT'),
    'release' => env('SENTRY_RELEASE'),
    'tracesSampleRate' => 0.1, // Sample 10% of traces
    'beforeSend' => function ($event) {
        // Skip 404s if you want
        if ($event['level'] === 'info') {
            return null;
        }
        return $event;
    },
]);

LightTrace automatically groups errors by fingerprint — one bug produces one issue in your dashboard, not a thousand duplicate alerts. You can read a stack trace to spot the root cause, and a single grouping means one fix address all occurrences.

Faster debugging with source context and releases

When debugging production, you want a tight loop from error to code. Tag every release so you can spot which deploy introduced a regression:

// In your deployment script:
\Sentry\init([
    'release' => 'app@' . shell_exec('git rev-parse HEAD'),
]);

Once you tag releases, you can correlate errors to specific deploys. A regression that appears after version 1.2.3 points immediately to what changed. This turns production debugging from a guessing game into a methodical process, which is why tracking release context is one of the core error tracking best practices.

LightTrace can link stack frames directly to GitHub if you've connected your repository. Then an exception's trace becomes a one-click journey from the dashboard to the exact line in your repo. For a deeper guide, see how to add error tracking to any app.

Real-world impact: From hours to minutes

As your app scales, error tracking becomes indispensable. You'll catch edge cases your testing missed, find bugs your users never reported, and cut your mean-time-to-resolution from hours to minutes. Laravel's HTTP-request-aware context makes this even simpler — the SDK knows about your routes, middlewares, and authenticated users, so you get a rich picture of every failure. Compare this to manually parsing log files or piecing together stack traces from error emails, and you'll see why reducing MTTR is a core benefit of production error tracking.

The next time an exception lands in your production logs, it'll be sitting in your error dashboard with full request context, breadcrumbs, and user info already attached. That's the difference between discovering bugs by accident and catching them in real time.