Überprüfung und typische Probleme - Next.js

Ein kontrolliertes Testereignis

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

await getRay().captureMessage('DockRay-Kontrollmeldung');

Rufe das aus einer temporären Route in einer Staging-Umgebung auf und entferne sie gleich nach dem erfolgreichen Test - weitere Aufrufe verbrauchen das Monatskontingent. Die Meldung sollte im Panel unter Fehler des Projekts erscheinen, auf das der Token zeigt, mit erhaltenem Umgebungsnamen.

Typische Probleme

Der private Schlüssel landete im Browser-Code

Hat RAY_PRIVATE_KEY den Präfix NEXT_PUBLIC_ bekommen, hat Next ihn beim ersten Build in das Client-Bundle eingebettet - der Schlüssel ist damit bereits öffentlich. Das Umbenennen der Variable macht das Leck nicht rückgängig: widerrufe den Schlüssel im Panel und erzeuge einen neuen.

Fehler aus der Middleware werden nicht gemeldet

Middleware ist immer ein Edge-Bundle. Ein Import vom Haupteinstiegspunkt (@dockcodes/dock-ray-next) statt /edge, oder ein fehlendes withRayMiddleware um die Middleware-Funktion, ist die häufigste Ursache.

Eine Edge-Meldung kommt trotz korrekter Einrichtung nicht an

Ein Edge-Aufruf kann in dem Moment eingefroren werden, in dem die Funktion einen Wert zurückgibt. Der Edge-Wrapper wartet genau deshalb auf seinen Report - stelle sicher, dass der Fehler tatsächlich durch withRayMiddleware oder rayRequestError aus /edge läuft und nicht durch einen eigenen, unfertigen ray.report()-Aufruf.

JavaScript-Fehler aus dem Browser kommen nicht an

Die Route antwortet immer mit 202, egal ob sie die Meldung angenommen hat - das ist beabsichtigt, damit ein Aufrufer nichts über die Schutzmechanismen erfährt. Prüfe einzeln: ist NEXT_PUBLIC_RAY_JS_ERRORS=true gesetzt (eine Änderung braucht einen neuen Build, weil sie zur Build-Zeit ins Bundle eingebacken wird), ist RayBrowserReporting im Root-Layout eingebunden, hat app/api/ray/browser/route.ts ein export const runtime = 'nodejs', und - am leichtesten übersehen - stehen auf dem Server überhaupt RAY_TOKEN und RAY_PRIVATE_KEY? Ohne sie antwortet die Route weiterhin mit 202, leitet aber nichts weiter.

Transaktionen fehlen

RAY_TRACES_SAMPLE_RATE steht standardmäßig auf 0. Token und Schlüssel allein schalten die Messung nicht ein.

Ein Vercel-Preview-Deployment meldet sich als Produktion

VERCEL_ENV und VERCEL_GIT_COMMIT_SHA werden nur genutzt, wenn RAY_ENVIRONMENT und RAY_RELEASE nicht gesetzt sind. Steht in den Vercel-Projekteinstellungen RAY_ENVIRONMENT=production für alle Umgebungen zugleich, funktioniert die automatische Erkennung nicht mehr und jeder Preview meldet sich als Produktion.

Ein Fehler zerfällt in viele Einträge

Das Panel gruppiert über den Fingerabdruck sha256(Projekt-Token + Typ + Meldung). Next fügt Tags aus dem Routenkontext hinzu, ändert damit aber weder Typ noch Meldung - eine in die Ausnahmemeldung eingesetzte Kennung zerlegt einen Fehler weiterhin in tausend Zeilen.

Das Panel antwortet 200, aber es gibt kein Ereignis

Eine Antwort 200 {"success": false} bedeutet, dass das Konto sein monatliches Fehlerkontingent aufgebraucht hat. Die Integration behandelt das nicht als Störung - zu Recht. Das Kontingent siehst du im Konto-Dashboard; bis zum Monatsende wird es aus der erfassten Nutzung berechnet, Fehler zu löschen setzt es also nicht zurück.

Es funktioniert weiterhin nicht

Arbeite die Checkliste zur Fehlerbehebung durch, und wenn das nicht hilft, schreib uns. Nenne den Projektnamen, die Version der Integration und ungefähr die Uhrzeit des Tests: das verkürzt den Weg zur Antwort.