Weryfikacja i typowe problemy - Node.js

Kontrolowane zdarzenie

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

Metody raportujące zwracają obietnicę - w skrypcie, który kończy działanie od razu po wywołaniu, poprzedź je await albo ray.report(), inaczej proces zdąży się zamknąć, zanim żądanie wyjdzie.

Typowe problemy

ray.enabled jest false mimo ustawionych zmiennych

Klient nie czyta process.env sam - poświadczenia zawsze trafiają do konstruktora jawnie, tak jak w przykładach z tego działu. Sprawdź, czy token i privateKey rzeczywiście dotarły jako niepuste ciągi; pusty string liczy się tak samo jak brak wartości.

Build się nie kompiluje w Edge Runtime albo na Cloudflare Workers

Objaw to zwykle błąd bundlera w stylu „Module not found: Can't resolve 'node:fs'". Główne wejście pakietu importuje node:fs, node:os i node:zlib, których taki bundel nie rozwiąże. Zaimportuj @dockcodes/dock-ray/edge zamiast głównego wejścia - API zostaje to samo, znika tylko kontekst źródła w stosie i kompresja gzip.

installGlobalHandlers() nic nie robi, dopóki go nie wywołasz

Przechwytywanie nieobsłużonych awarii procesu jest domyślnie wyłączone - trzeba je włączyć świadomie, bo zmienia sposób, w jaki proces kończy pracę przy błędzie krytycznym. Po wywołaniu ray.installGlobalHandlers() zgłoszony uncaughtException kończy się wywołaniem process.exit(1), chyba że przekażesz { exitOnUncaught: false }. unhandledRejection jest tylko raportowany i nie zamyka procesu.

Część zdarzeń znika przy dużym ruchu

Kolejka report() trzyma najwyżej 50 równoległych zgłoszeń na cały proces; nadwyżka jest odrzucana bez śladu w logu. Sprawdź też sampleRate, jeśli został obniżony - domyślnie wynosi 1 i wysyła wszystko.

Transakcje rozsypują się na tysiące różnych wierszy

Nazwa transakcji bierze się z wzorca trasy zarejestrowanego w routerze (req.route.path w Express, routerPath w Fastify). Jeśli adapter działa na żądaniu, które nie trafiło jeszcze w żaden zarejestrowany handler - odpowiedź 404, middleware ustawione przed routerem - wzorca nie ma i nazwa spada do surowej ścieżki z adresu, więc każdy odrębny adres staje się osobnym wierszem.

Kody 4xx nie trafiają do panelu jako błędy

To zamierzone działanie domyślnego shouldReport: raportowane są tylko odpowiedzi 5xx, bo 4xx to zwykle pomyłka wywołującego, nie awaria aplikacji. Żeby to zmienić, przekaż własną funkcję shouldReport do adaptera.

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.