Weryfikacja i typowe problemy - Next.js

Kontrolowane zdarzenie testowe

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

await getRay().captureMessage('Kontrolny komunikat DockRay');

Wywołaj to z tymczasowej trasy na środowisku testowym i usuń ją zaraz po udanym teście - kolejne wywołania zużywają miesięczny limit błędów. Komunikat powinien pojawić się w panelu w sekcji Błędy projektu wskazanego przez token, z zachowaną nazwą środowiska.

Typowe problemy

Klucz prywatny trafił do kodu przeglądarki

Jeśli RAY_PRIVATE_KEY dostał przedrostek NEXT_PUBLIC_, Next wkleił go do paczki klienta przy pierwszym buildzie - to znaczy, że klucz jest już publiczny. Zmiana nazwy zmiennej na poprawną nie cofa wycieku: odwołaj klucz w panelu i wygeneruj nowy.

Błędy z middleware nie są raportowane

Middleware jest zawsze bundlem brzegowym. Import z głównego punktu wejścia (@dockcodes/dock-ray-next) zamiast /edge albo brak withRayMiddleware wokół funkcji middleware to najczęstsza przyczyna.

Zgłoszenie z Edge nie dochodzi mimo poprawnej konfiguracji

Wywołanie na Edge bywa zamrażane w chwili, w której funkcja zwraca wynik. Wrapper brzegowy czeka na wysłanie raportu specjalnie z tego powodu - upewnij się, że błąd faktycznie przechodzi przez withRayMiddleware albo rayRequestError z /edge, a nie przez własny, niedoczekany ray.report().

Błędy JavaScriptu z przeglądarki nie docierają

Trasa zawsze odpowiada 202, niezależnie od tego, czy przyjęła zgłoszenie - to celowe, żeby wywołujący nie dowiedział się niczego o zabezpieczeniach. Sprawdź osobno: czy NEXT_PUBLIC_RAY_JS_ERRORS=true jest ustawione (zmiana wymaga przebudowania aplikacji, bo to zmienna wpisywana w bundlu przy buildzie), czy RayBrowserReporting jest zamontowany w głównym layoucie, czy trasa app/api/ray/browser/route.ts ma export const runtime = 'nodejs', i - co najłatwiej przeoczyć - czy serwer w ogóle ma ustawione RAY_TOKEN i RAY_PRIVATE_KEY. Bez nich trasa nadal odpowiada 202, tylko nic nie przekazuje dalej.

Transakcje nie pojawiają się

RAY_TRACES_SAMPLE_RATE domyślnie wynosi 0. Sam token i klucz nie włączają pomiaru ruchu.

Deployment preview na Vercelu zgłasza się jako produkcja

VERCEL_ENV i VERCEL_GIT_COMMIT_SHA są używane tylko wtedy, gdy RAY_ENVIRONMENT i RAY_RELEASE nie są ustawione. Jeśli w ustawieniach projektu na Vercelu wpisano RAY_ENVIRONMENT=production dla wszystkich środowisk naraz, automatyczne rozpoznawanie przestaje działać i każdy preview zgłasza się jako produkcja.

Ten sam błąd rozbija się na wiele wpisów

Panel grupuje po odcisku sha256(token projektu + typ + komunikat). Next dokłada do tego tagi z kontekstu trasy, ale nie zmienia typu ani treści komunikatu - identyfikator wklejony w treść wyjątku nadal rozbija jeden błąd na tysiąc wierszy.

Panel odpowiada 200, ale zdarzenia nie ma

Odpowiedź 200 {"success": false} znaczy, że konto wyczerpało miesięczny limit błędów. Integracja nie traktuje tego jak awarii - i słusznie. Limit widzisz na pulpicie konta; do końca miesiąca liczy się z zapisanego zużycia, więc nie zresetuje go usunięcie błędów.

Nadal nie działa

Przejdź przez listę kontrolną braku danych w panelu, a jeśli to nie pomoże - napisz do nas. Podaj nazwę projektu, wersję integracji i przybliżoną godzinę testu: to skraca drogę do odpowiedzi.