Konfiguracja - Nuxt
Na tej stronie Opcje modułu
Opcje modułu
Wszystkie ustawia się w kluczu ray w nuxt.config.ts; poświadczenia zwykle nadpisuje się zmiennymi NUXT_RAY_*.
| Opcja | Domyślnie | Znaczenie |
|---|---|---|
token, privateKey | - | poświadczenia projektu; bez obu moduł milczy |
url | https://dockray.io | instancja DockRay |
environment | NODE_ENV | kolumna środowiska w panelu |
release | - | wdrożona wersja |
sampleRate | 1 | udział wysyłanych zdarzeń błędów |
tracesSampleRate | 0 | udział wysyłanych transakcji; 0 wyłącza pomiar |
sendDefaultPii | false | dołącza adres IP i user agenta |
ignorePaths | /_nuxt, /__nuxt, /health, /metrics | ścieżki nigdy niemierzone |
browser.enabled | false | zbieranie błędów JavaScriptu |
browser.endpoint | /api/_ray/browser | trasa, która je odbiera |
browser.sampleRate | 1 | udział zgłaszanych błędów przeglądarki |
Środowiska
Każde środowisko powinno raportować pod jednoznaczną nazwą - production, staging, preview. Nazwa jest kolumną w panelu i filtrem na liście błędów, więc bez niej awaria z produkcji wygląda dokładnie tak samo jak błąd wywołany w testach. Środowisko lokalne zostaw bez poświadczeń: bez tokenu i klucza integracja ładuje się i milczy, więc nie musisz jej wyłączać osobnym warunkiem.
Co raportuje serwer
Moduł rejestruje wtyczkę Nitro na czterech hookach:
| Hook | Robi |
|---|---|
request | zapisuje czas rozpoczęcia |
error | raportuje nieobsłużone błędy serwera, otagowane dopasowaną trasą |
afterResponse | zamyka transakcję kodem odpowiedzi |
close | wysyła oczekujące raporty przed zakończeniem procesu |
Transakcje wychodzą na afterResponse, czyli po tym, jak odpowiedź już dotarła do gościa - nic nie jest wysyłane w trakcie jego oczekiwania. createError({ statusCode: 404 }) i każdy inny 4xx to pomyłka wywołującego, nie awaria aplikacji, więc raportowane są wyłącznie kody 5xx.
Nazwy transakcji
Transakcja bierze nazwę z dopasowanej trasy (GET /orders/:id, nie GET /orders/8123), więc jedna trasa zostaje jednym wierszem w panelu niezależnie od tego, ile identyfikatorów przez nią przeszło.
Node, workery i Edge
Ten sam kod działa na Node i na workerach: zdarzenie jest czytane zarówno przez event.node.req, jak i przez kształt Request z Fetch API, więc wdrożenie na Cloudflare albo Vercel Edge nie potrzebuje drugiej ścieżki kodu.
Błędy Vue i JavaScriptu z przeglądarki
Domyślnie wyłączone:
ray: {
browser: {
enabled: true,
},
}To rejestruje trasę Nitro i wtyczkę kliencką. Przeglądarka zgłasza błąd do Twojej aplikacji, nigdy do panelu: nie ma klucza projektu, a nadanie jej klucza byłoby jego opublikowaniem. Serwer przekazuje każde zgłoszenie już swoim kluczem i dokłada kopertę - środowisko, wersję, znacznik czasu - więc przeglądarka nie wybiera, do którego środowiska trafią jej błędy.
Vue połyka błędy komponentów we własnym handlerze, więc window.onerror nigdy ich nie widzi. Wtyczka wpina dlatego oba hooki Nuxt: vue:error dla błędów renderowania i cyklu życia, app:error dla błędu krytycznego przy starcie.
Trasa odpowiada 202 na wszystko - zgłoszenie poprawne, uszkodzone, odrzucone przez limit - więc wywołujący nie dowiaduje się niczego o zabezpieczeniach. Odrzuca ciała powyżej 16 kB i przyjmuje dwadzieścia zgłoszeń na adres na minutę. Kolektor po stronie przeglądarki sam się ogranicza: jedno zgłoszenie na odrębny błąd na odsłonę, domyślnie najwyżej dziesięć na odsłonę, a ResizeObserver loop i Script error. z obcej domeny są odsiewane.
Ręczne raportowanie
window.DockRay?.captureException(error);
window.DockRay?.captureMessage('Checkout step skipped');Ochrona klucza prywatnego
Klucz prywatny jest sekretem projektu, a nie identyfikatorem. Trzymaj go w zmiennych środowiskowych, w menedżerze sekretów albo w konfiguracji serwera - nigdy w repozytorium, w logach, na zrzucie ekranu ani w kodzie wysyłanym do przeglądarki. Jeden projekt może mieć wiele kluczy, więc produkcja i środowisko testowe powinny dostać osobne: każdy odwołuje się niezależnie, bez przerywania raportowania z pozostałych. Podejrzenie ujawnienia klucza jest wystarczającym powodem, aby go odwołać i wygenerować nowy.