Konfiguration - Next.js

3 Min. Lesezeit Aktualisiert: 11.09.2026

Umgebungsvariablen

Die Integration hat keine eigene Konfigurationsdatei - alles wird beim Aufruf von initRay() aus der Umgebung gelesen.

Variable	Standard	Bedeutung
`RAY_TOKEN`, `RAY_PRIVATE_KEY`	-	Projekt-Zugangsdaten; ohne beide bleibt die Integration still
`RAY_URL`	`https://dockray.io`	DockRay-Instanz
`RAY_ENVIRONMENT`	`VERCEL_ENV`, dann `NODE_ENV`	Umgebungsspalte im Panel
`RAY_RELEASE`	`VERCEL_GIT_COMMIT_SHA`	Version der bereitgestellten Anwendung
`RAY_SAMPLE_RATE`	`1`	Anteil gesendeter Fehlerereignisse
`RAY_TRACES_SAMPLE_RATE`	`0`	Anteil gesendeter Transaktionen; `0` deaktiviert die Messung
`RAY_SEND_DEFAULT_PII`	`false`	hängt IP-Adresse und User-Agent des Besuchers an

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.

Transaktionsnamen und Tags

Jede Meldung aus onRequestError trägt Tags aus dem Kontext, den Next liefert: router (App oder Pages), route - das Routenmuster, etwa /orders/[id], statt des konkreten Pfads - route_type und render_source. Das Routenmuster sorgt dafür, dass eine Route eine Zeile im Panel bleibt, egal wie viele Kennungen durch sie gelaufen sind.

Was aus einer Meldung verschwindet

Bevor ein Ereignis DockRay erreicht, entfernt die Integration Authorization, Cookie, Set-Cookie, X-Api-Key und den eigenen Token des Browser-Kollektors aus den Headern. IP-Adresse und User-Agent des Besuchers werden nur mit RAY_SEND_DEFAULT_PII=true angehängt - ohne das trägt eine Meldung gar kein user-Feld.

JavaScript-Fehler aus dem Browser

Standardmäßig deaktiviert. Das Einschalten braucht zwei Teile.

Die Route, die sie empfängt - app/api/ray/browser/route.ts:

import { createBrowserErrorRoute } from '@dockcodes/dock-ray-next';

export const POST = createBrowserErrorRoute();
export const runtime = 'nodejs';

Der Kollektor, einmal im Root-Layout eingebunden:

import { RayBrowserReporting } from '@dockcodes/dock-ray-next/client';

export default function RootLayout({ children }) {
    return (
        <html>
            <body>
                <RayBrowserReporting />
                {children}
            </body>
        </html>
    );
}

NEXT_PUBLIC_RAY_JS_ERRORS=true schaltet den Kollektor ein - der Präfix ist hier bewusst gewählt, denn das Feld trägt nur ein Flag, kein Geheimnis.

Der Browser meldet an deine Route, nie direkt an das Panel: Die Authentifizierung braucht den privaten Projektschlüssel, und ein Schlüssel im Client-Bundle ist ein veröffentlichter Schlüssel. Dein Server leitet jede Meldung mit seinem eigenen Schlüssel weiter und füllt den Umschlag aus - ID, Zeitstempel, Umgebung, Release -, der Browser wählt also nie, in welcher Umgebung seine Fehler landen.

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 aus dem Browser

'use client';
import { captureBrowserException } from '@dockcodes/dock-ray-next/client';

export default function GlobalError({ error }) {
    captureBrowserException(error);

    return <html><body><h1>Etwas ist schiefgelaufen</h1></body></html>;
}

Vercel

Wenn RAY_ENVIRONMENT und RAY_RELEASE nicht gesetzt sind, nimmt die Integration VERCEL_ENV als Umgebung und VERCEL_GIT_COMMIT_SHA als Release, ein Preview-Deployment meldet sich also nicht als Produktion.

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.