Flare

Error Tracking und Performance Tracing ueber Flare (Spatie). Primaere Fehlerueberwachung mit Fokus auf Laravel-native Integration, ergaenzt durch Laravel Nightwatch.

Integration

Flare wird ueber spatie/laravel-flare eingebunden und registriert sich als Exception Handler:

// bootstrap/app.php
use Spatie\LaravelFlare\Facades\Flare;

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

Location: bootstrap/app.php

Architektur

graph LR
    A["Exception"] --> B["Laravel Exception Handler"]
    B --> D["Flare"]
    B --> N["Nightwatch"]
    D --> E["Error Reports"]
    D --> F["Performance Traces"]
    F --> G["Sampling (10%)"]

Features

Feature	Beschreibung
Error Tracking	Automatische Erfassung aller unbehandelten PHP-Exceptions
Performance Tracing	Request-Traces mit konfigurierbarer Sampling-Rate
Log Events	Log-Statements werden als Events an Flare gesendet
Share Button	Laravel Error Page mit Share-Funktion fuer Fehler-Details
Data Censoring	Automatische Zensierung von Passwoertern, API-Keys, Tokens

Konfiguration

Location: config/flare.php

Collects

Flare sammelt automatisch Kontext-Informationen (Logs, Queries, Request-Daten). Ueber ignore und extra koennen Collectors deaktiviert oder hinzugefuegt werden:

'collects' => FlareConfig::defaultCollects(
    ignore: [],
    extra: []
),

Data Censoring

Sensible Daten werden automatisch aus Reports entfernt:

Bereich	Zensierte Felder
Body Fields	password, password_confirmation
Headers	API-KEY, Authorization, Cookie, Set-Cookie, X-CSRF-TOKEN, X-XSRF-TOKEN
Client IPs	Nicht zensiert (konfigurierbar)
Cookies	Nicht zensiert (konfigurierbar)
Session	Nicht zensiert (konfigurierbar)

Performance Tracing

Traces erfassen den Ablauf von Requests inkl. DB-Queries, Queue-Jobs und HTTP-Calls. Die Sampling-Rate bestimmt, welcher Anteil der Requests getrackt wird:

'trace' => env('FLARE_TRACE', true),
'sampler' => [
    'class' => \Spatie\FlareClient\Sampling\RateSampler::class,
    'config' => [
        'rate' => env('FLARE_SAMPLER_RATE', 0.1), // 10% der Requests
    ],
],

Error Grouping

Flare gruppiert Fehler automatisch. Fuer spezifische Exceptions kann das Grouping ueberschrieben werden:

'overridden_groupings' => [
    // ConnectionException::class => OverriddenGrouping::ExceptionMessageAndClass,
],

Log Events

Log-Statements (Log::info(), Log::error() etc.) werden als Events an Flare gesendet:

'send_logs_as_events' => true,

Frontend-Errors (ClientError-Pfad)

Frontend-JS-Errors werden über POST /api/client-errors ans Backend geschickt (resources/js/error-reporter.js fängt window.error, unhandledrejection und console.error('[Postbox] …')). Seit 2026-05-04 läuft der Pfad NICHT mehr als Server-Exception, sondern als Log-Event:

// bootstrap/app.php
$exceptions->report(function (ClientError $e): void {
    Log::channel('client')->warning($e->getMessage(), $e->context());
})->stop();

• ->stop() hält die Default-Exception-Pipeline an.

⚠️ Die Absicht dahinter geht auf Produktion nicht auf, gemessen am 2026-09-04. Diese Stelle sagte bis dahin „Flare-Error-Liste bleibt sauber (PHP-Bugs only)". Sie ist es nicht: In der Liste der ungelösten Fehler steht App\Exceptions\ClientError mit 116 Vorkommen, Datei app/Http/Controllers/Api/ClientErrorController.php, und die jüngste Meldung trägt 65 Stack-Frames. Ein Log-Event trägt keinen PHP-Stacktrace — das ist ein echter Exception-Report, also genau das, was ->stop() verhindern sollte.

Die naheliegende Erklärung: Flare hängt nicht im Log-Stack (der Default ist single,nightwatch), sondern am Exception-Handler, und ->stop() beendet die Laravel-Reportable-Kette, nicht Flares eigenen Pfad. Belegt ist bisher nur die Wirkung, nicht die Ursache — verfolgt wird das in PBX-289. Bis dahin gilt: die Trennung zwischen Frontend- und Backend-Fehlern existiert in der Absicht, nicht in der Ansicht.

• Log::channel('client') schreibt in storage/logs/client-errors.log (daily, 30 Tage Retention).
• Flare bekommt die Errors trotzdem über send_logs_as_events=true — aber als Log-Event statt Exception. Frontend-Source/URL/Line/Stack stehen im Log-Context und damit im Flare-Custom-Context.

Browser-Extension-Filter: der Reporter ignoriert Errors aus Sources chrome-extension://, moz-extension://, safari-web-extension://, safari-extension://, webkit-masked-url://, about: — die kommen aus User-Extensions (Translator, Adblocker, Password-Manager) und sind keine Bugs in unserem Code.

Application Version

Flare zeigt die deployed App-Version (Git Commit Hash) im Dashboard an. Die Version wird in AppServiceProvider::boot() ueber Flare::withApplicationVersion() gesetzt:

1. Explizit: APP_VERSION env-Variable (wird beim Deployment gesetzt, z.B. Git Commit Hash)
2. Auto-Detect: Falls APP_VERSION nicht gesetzt, wird der Git Commit Hash automatisch aus .git/ gelesen

Damit sind Fehler in Flare dem exakten Deploy-Commit zuordenbar.

Location: app/Providers/AppServiceProvider.php

.env Variablen

Variable	Default	Beschreibung
FLARE_KEY	--	Flare API Key (erforderlich fuer Error Reporting)
FLARE_TRACE	true	Performance Tracing aktivieren/deaktivieren
FLARE_SAMPLER_RATE	0.1	Sampling-Rate fuer Traces (0.0 = keine, 1.0 = alle)
APP_VERSION	--	Deployed Commit Hash (fuer Flare Version-Tagging)

Admin Sidebar Link

Im Admin-Bereich gibt es einen direkten Link zu Flare Errors:

https://flareapp.io/103600-postbox/errors

Relevante Dateien

Bereich	Pfad
Flare Config	config/flare.php
Exception Handler	bootstrap/app.php
Package	spatie/laravel-flare (composer.json)