Konfiguration - Drupal
Wo die Konfiguration liegt
Verwaltung → Konfiguration → Entwicklung → DockRay, also /admin/config/development/dock-ray. Das Formular zeigt den aktuellen Konfigurationsstatus, das Ergebnis des letzten Tests und eine Schaltfläche Testereignis senden, die die Verbindung ohne Seitenwechsel prüft.
Konfigurationsquelle
Konfigurationsquelle entscheidet, wie ein Override aus der settings.php und die im Formular gespeicherten Werte zusammenspielen:
| Quelle | Verhalten |
|---|---|
| Auto (Standard) | ein in der settings.php gesetzter Schlüssel gewinnt für sein Feld, alles andere kommt aus dem Formular. Genau so verhielt sich das Modul, bevor dieses Feld existierte - niemandes settings.php hört auf zu funktionieren. |
| Nur settings.php | Token, Schlüssel und URL aus dem Formular werden ignoriert, auch wenn sie gefüllt sind; ein Feld ohne passenden Schlüssel fällt auf seinen Standardwert zurück, nicht auf das Formular |
| Nur dieses Formular | die settings.php wird ignoriert, selbst wenn sie einen Override definiert - nützlich, wenn eine gemeinsame Settings-Datei ein Standardprojekt festschreibt und eine Website ihr eigenes braucht |
Gesperrte Felder werden mit dem tatsächlich wirksamen Wert und einer Begründung angezeigt. Sie übermitteln diesen Wert weiterhin mit dem Formular: ein deaktiviertes Form-API-Element übergibt #default_value, statt den Schlüssel wegzulassen - Speichern bei gesperrtem Feld kann das Gespeicherte also nicht leeren.
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.
Wie das Melden funktioniert
Das Modul registriert einen Logger-Kanal. Drupal verwandelt ohnehin jeden PHP-Fehler und jede unbehandelte Ausnahme in einen Log-Eintrag, ein Kanal deckt also alles ab - und es gibt keinen zweiten Fehlerhandler, der mit dem Kern konkurriert.
minimum_level ist eine Schwere nach RFC 5424: 3 (Error) meldet Fehler, kritische Ereignisse, Alerts und Notfälle und ignoriert Warnungen und Notices. Ein Eintrag mit Ausnahme wird samt Stacktrace gemeldet, der Rest wird zu Meldungen.
| Stufe | Umfasst |
|---|---|
2 Critical | nur kritische Ausfälle und darüber |
3 Error | empfohlen: Fehler und alles Schwerwiegendere |
4 Warning | auch Warnungen - auf einer großen Website deutlich mehr Ereignisse |
Transaktionen
Die Bearbeitungszeit wird nur gemessen, wenn traces_sample_rate über null liegt. Eine Transaktion öffnet auf kernel.request und schließt auf kernel.terminate. Während der Anfrage geht nichts hinaus: Ereignisse sammeln sich und verlassen die Warteschlange aus einem Shutdown-Handler, sobald die Antwort ausgeliefert ist - ein langsames Panel verzögert also nie eine Seite.
JavaScript-Fehler
Standardmäßig aus. Nach dem Aktivieren lädt das Modul auf Nicht-Admin-Seiten einen Kollektor, der window.onerror und unbehandelte Promise-Rejections an die Website meldet, nicht an das Panel: ein Browser kann sich ohne den privaten Schlüssel nicht bei DockRay authentifizieren, und dieser wäre dann im Seitenquelltext lesbar.
Die Meldungen gehen an POST /dock-ray/browser-error, begrenzt auf 16 kB und über Drupals Flood-Service auf 20 pro IP-Adresse und Stunde gedrosselt. Der Kollektor selbst wird von /dock-ray/collector.js ausgeliefert, weil das SDK im vendor/-Verzeichnis des Projekts liegt, bei den meisten Installationen also außerhalb des Docroots. Jede Anfrage antwortet 202, unabhängig davon, ob die Meldung angenommen wurde.
Melden aus eigenem Code
try {
$this->import();
}
catch (\Throwable $exception) {
\Drupal::service('dock_ray.hub')->captureException($exception);
throw $exception;
}\Drupal::logger('my_module')->error(...) erreicht DockRay ebenfalls - über denselben Kanal wie alles andere, eigener Code braucht also keine separate Integration.
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.