Konfiguration - Laravel

3 Min. Lesezeit Aktualisiert: 11.09.2026

Wo die Konfiguration liegt

Alles steht in config/ray.php, und jeder Wert hat ein Gegenstück in der .env.

Schlüssel	Standard	Bedeutung
`token`, `private_key`	-	Projekt-Zugangsdaten; ohne beide bleibt das Paket still
`url`	`https://dockray.io`	DockRay-Instanz
`environment`	`APP_ENV`	Umgebungsspalte im Panel
`release`	`null`	Version der ausgelieferten Anwendung
`sample_rate`	`1`	Anteil der gesendeten Fehlerereignisse
`traces_sample_rate`	`0`	Anteil der gesendeten Transaktionen; `0` deaktiviert die Messung
`send_default_user`	`true`	hängt ID, E-Mail und Namen des angemeldeten Benutzers an
`send_default_pii`	`false`	hängt IP-Adresse und User-Agent an
`ignore_exceptions`	`[]`	Ausnahmeklassen, die nie gemeldet werden
`ignore_transactions`	`horizon`, `telescope`, `_debugbar*`	nie gemessene Pfade, Muster wie in `Request::is()`
`options.max_request_body_size`	`medium`	`none`, `small`, `medium` oder `always`
`options.attach_stacktrace`	`false`	Stack auch bei einfachen Meldungen

Umgebungen

Jede Umgebung sollte unter einem eindeutigen Namen berichten - production, staging, preview. Der Name ist eine Spalte im Panel und ein Filter in der Fehlerliste; ohne ihn sieht ein Produktionsausfall genauso aus wie ein Fehler, den jemand im Test ausgelöst hat. Lass die lokale Umgebung ohne Zugangsdaten: ohne Token und Schlüssel lädt die Integration und bleibt still - ein eigener Schalter ist nicht nötig.

Was nicht gemeldet werden sollte

ignore_exceptions wirkt zusätzlich zu Laravels eigener dontReport-Liste, ValidationException, AuthenticationException und HttpException werden also ohne jede Konfiguration übersprungen. Ergänze hier die Ausnahmen, die in deiner Anwendung ein normales Ergebnis sind und keine Störung:

php

'ignore_exceptions' => [
    \App\Exceptions\PaymentDeclinedException::class,
    \Illuminate\Session\TokenMismatchException::class,
],

Die Regel ist einfach: zu DockRay gehört, worauf jemand reagieren soll. Eine erwartete abgelehnte Zahlung oder ein abgelaufener Formular-Token gehören zum Normalbetrieb und verbrauchen nur das Monatskontingent.

Transaktionsnamen

Transaktionen werden nach dem Routenmuster benannt - GET /orders/{order}, nicht GET /orders/8123. So bleibt eine Route eine Zeile im Panel, egal wie viele Kennungen durch sie laufen. Siehst du tausende einzelne Transaktionen, ist die Route fast immer ohne Parameter definiert.

Benutzerkontext

Die Middleware hängt ID, E-Mail-Adresse und Namen des angemeldeten Benutzers an. Schalte es mit RAY_SEND_DEFAULT_USER=false aus oder ersetze es durch eigene Felder:

php

Ray::setUser(['id' => $account->id, 'username' => $account->slug]);

IP-Adresse und User-Agent werden nur bei RAY_SEND_DEFAULT_PII=true angehängt. Das ist eine von der Benutzeridentität getrennte Entscheidung, weil sie auch Gäste betrifft.

Melden aus eigenem Code

php

use Dock\Ray\Laravel\Ray;
use Dock\Ray\Severity;

Ray::message('Nächtlicher Import zu spät beendet', Severity::warning());

Queues und Artisan-Befehle

Beide laufen außerhalb des HTTP-Middleware-Stacks, sie melden also Fehler, erzeugen aber keine Transaktionen. Der Hub ist ein Singleton für den ganzen Prozess: ein langlebiger Queue-Worker behält einen Client und eine Verbindung, statt sie pro Job neu aufzubauen.

Den privaten Schlüssel schützen

Der private Schlüssel ist ein Projektgeheimnis, keine Kennung. Bewahre ihn in Umgebungsvariablen, in einem Secret-Manager oder in der Serverkonfiguration auf - niemals im Repository, in Logs, auf einem Screenshot oder in Code, der an den Browser geht. Ein Projekt kann mehrere Schlüssel haben, deshalb sollten Produktion und Staging je eigene bekommen: jeder lässt sich einzeln widerrufen, ohne die übrigen zu unterbrechen. Der Verdacht, dass ein Schlüssel abgeflossen ist, genügt, um ihn zu widerrufen und einen neuen zu erzeugen.