Konfiguration - Nuxt

Modul-Optionen

Alles wird unter dem Schlüssel ray in nuxt.config.ts gesetzt; Zugangsdaten werden meist mit NUXT_RAY_*-Variablen überschrieben.

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 der Server meldet

Das Modul registriert ein Nitro-Plugin an vier Hooks:

Transaktionen gehen bei afterResponse hinaus, also nachdem die Antwort den Besucher bereits erreicht hat - während des Wartens wird nichts gesendet. createError({ statusCode: 404 }) und jeder andere 4xx ist ein Fehler des Aufrufers, keine Störung der Anwendung, deshalb werden nur 5xx-Codes gemeldet.

Transaktionsnamen

Eine Transaktion nimmt ihren Namen von der passenden Route (GET /orders/:id, nicht GET /orders/8123), eine Route bleibt also eine Zeile im Panel, egal wie viele Kennungen durch sie liefen.

Node, Worker und Edge

Derselbe Code läuft auf Node und auf Workern: Das Ereignis wird sowohl über event.node.req als auch über die Fetch-Request-Form gelesen, ein Cloudflare- oder Vercel-Edge-Deployment braucht also keinen zweiten Codepfad.

Vue- und JavaScript-Fehler aus dem Browser

Standardmäßig deaktiviert:

ray: {
    browser: {
        enabled: true,
    },
}

Das registriert die Nitro-Route und das Client-Plugin. Der Browser meldet an deine App, nie an das Panel: er hat keinen Projektschlüssel, und ihm einen zu geben würde ihn veröffentlichen. Der Server leitet jede Meldung mit seinem eigenen Schlüssel weiter und füllt den Umschlag aus - Umgebung, Release, Zeitstempel -, der Browser wählt also nie, in welcher Umgebung seine Fehler landen.

Vue verschluckt Komponentenfehler im eigenen Handler, window.onerror sieht sie also nie. Deshalb bindet das Plugin beide Nuxt-Hooks ein: vue:error für Render- und Lifecycle-Fehler, app:error für einen fatalen Boot-Fehler.

Die Route antwortet auf alles mit 202 - eine gültige Meldung, eine fehlerhafte, eine vom Limit abgelehnte -, ein Aufrufer erfährt also nichts über die Schutzmechanismen. Sie verwirft Bodies über 16 KB und erlaubt zwanzig Meldungen pro Adresse und Minute. Der Kollektor im Browser begrenzt sich zusätzlich selbst: eine Meldung pro eigenständigem Fehler und Seitenaufruf, standardmäßig höchstens zehn pro Seitenaufruf, wobei ResizeObserver loop und fremdes Script error. herausgefiltert werden.

Manuelles Melden

window.DockRay?.captureException(error);
window.DockRay?.captureMessage('Checkout step skipped');

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.