Konfiguration - PHP

Wissenswerte Optionen

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.

in_app_exclude entscheidet über die Lesbarkeit des Stacks

Das ist die am meisten unterschätzte Option des SDK. Frames unterhalb der in in_app_exclude genannten Pfade werden als Fremdcode markiert, das Panel zeigt also die Fehlerstelle in deiner Anwendung statt des tiefsten Frames in einer Bibliothek:

init([
    'in_app_exclude' => [__DIR__.'/../vendor'],
]);

Ohne das sieht jeder Fehler aus, als wäre er in vendor/ entstanden - und nach Jira und Notion geht genau der bedeutsame Teil des Stacks, also die als Anwendungscode markierten Frames.

Wann Ereignisse hinausgehen

Standardmäßig nach der Antwort. Ereignisse werden während der Anfrage gesammelt und aus einem Shutdown-Handler ausgeliefert, wenn PHP-FPM oder LiteSpeed die Verbindung zum Browser schon geschlossen hat - ein langsamer oder nicht erreichbarer Monitoring-Dienst verzögert die Seite für den Besucher dann nicht. Wo das SAPI die Verbindung nicht früher schließen kann (etwa mod_php), wird die Warteschlange dennoch beim Shutdown geleert, das Melden passiert also nicht mitten in der Bearbeitung.

Die Warteschlange hält höchstens 50 Ereignisse pro Anfrage; darüber werden neue verworfen, da wiederholte Ereignisse ohnehin über den Fingerabdruck gruppiert werden. 'send_after_response' => false schaltet auf sofortiges Senden um; in der CLI ist das schon Standard, weil ein langlebiger Worker Berichte nicht bis zum Prozessende halten sollte.

HTTP-Transaktionen

use Dock\Ray\Framework\HttpTransaction;

$transaction = HttpTransaction::start('GET /checkout', $url, 'GET');

$transaction->measureHandling('app.handle');

// ... Anfrage bearbeiten ...

$transaction->finish($response->getStatusCode());

Das erste Argument ist ein Routenmuster, keine konkrete Adresse: GET /orders/{order}, nicht GET /orders/8123. Sonst zerfällt die Transaktionsliste in tausende Einträge. Transaktionen gehen nur bei einer traces_sample_rate über null hinaus.

Ereignisse anreichern

use Dock\Ray\Breadcrumb;
use function Dock\Ray\{addBreadcrumb, configureScope};

addBreadcrumb(new Breadcrumb(
    Breadcrumb::LEVEL_INFO,
    Breadcrumb::TYPE_DEFAULT,
    'auth',
    'User logged in'
));

configureScope(function (\Dock\Ray\State\Scope $scope) {
    $scope->setTag('feature', 'payments');
    $scope->setUser(['id' => 42, 'email' => 'user@example.com']);
});

Tags sind der günstigste Weg, im Panel einen Bereich der Anwendung zu filtern. Setze Benutzerdaten bewusst - das sind personenbezogene Daten, und send_default_pii ist nicht ohne Grund standardmäßig aus.

Browserfehler

Ein Browser kann sich nicht direkt bei DockRay authentifizieren, denn der private Projektschlüssel muss auf dem Server bleiben. Das SDK liefert daher ein Kollektor-Skript und einen serverseitigen Normalisierer, und das Ereignis nimmt diesen Weg:

Browser  →  deine Anwendung  →  DockRay
         (ohne Schlüssel)     (Projektschlüssel)

use Dock\Ray\Browser\BrowserEvent;
use Dock\Ray\Browser\Collector;

// Beim Rendern der Seite: dem Kollektor den eigenen Endpunkt nennen.
$config = Collector::config(endpoint: '/errors/browser', token: $csrfToken);

// Collector::scriptPath() ist die Datei zum Ausliefern oder Einbetten.

// Beim Empfang: alles in $payload ist nicht vertrauenswürdig.
$event = BrowserEvent::fromArray($payload, $referer, $userAgent);

if ($event !== null) {
    $hub->captureEvent($event);
}

fromArray() gibt null für alles zurück, was es nicht in ein Ereignis verwandeln kann, und kürzt jede behaltene Zeichenkette. Die Schranken des Endpunkts schreibst du selbst - ein CSRF-Token, ein Body-Größenlimit und ein Limit pro IP-Adresse sind genau das, was unsere Plugins verwenden. Der Kollektor begrenzt sich ebenfalls: eine Meldung pro eigenständigem Fehler pro Seitenaufruf und zehn pro Seitenaufruf, ResizeObserver loop und Cross-Origin-Script error. werden ausgesiebt.

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.