Konfiguracja - Next.js

Zmienne środowiskowe

Integracja nie ma własnego pliku konfiguracyjnego - wszystko czyta ze środowiska w chwili wywołania initRay().

Ś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.

Nazwy transakcji i tagi

Każde zgłoszenie z onRequestError niesie tagi zbudowane z kontekstu, który podaje Next: router (App albo Pages), route - wzorzec trasy, na przykład /orders/[id], a nie konkretną ścieżkę - route_type i render_source. Dzięki wzorcowi trasy jedna trasa zostaje jednym wierszem w panelu niezależnie od tego, ile identyfikatorów przez nią przeszło.

Co znika z raportu

Zanim zdarzenie trafi do DockRaya, integracja usuwa z nagłówków Authorization, Cookie, Set-Cookie, X-Api-Key oraz własny token kolektora przeglądarki. Adres IP i user agent gościa dołączane są tylko przy RAY_SEND_DEFAULT_PII=true - bez tego zgłoszenie w ogóle nie niesie pola user.

Błędy JavaScriptu z przeglądarki

Domyślnie wyłączone. Włączenie wymaga dwóch elementów.

Trasy, która je odbiera - app/api/ray/browser/route.ts:

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

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

Kolektora, montowanego raz w głównym layoucie:

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

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

Zmienna NEXT_PUBLIC_RAY_JS_ERRORS=true włącza kolektor - ten przedrostek jest tu celowy, bo pole niesie tylko flagę, a nie sekret.

Przeglądarka zgłasza błąd do Twojej trasy, nigdy bezpośrednio do panelu: uwierzytelnienie wymaga klucza prywatnego projektu, a klucz w paczce klienta jest kluczem opublikowanym. Twój serwer przekazuje każde zgłoszenie już z własnym kluczem, dokładając kopertę zdarzenia - identyfikator, znacznik czasu, środowisko, wersję - więc przeglądarka nie wybiera, do którego środowiska trafią jej błędy.

Trasa odpowiada 202 na wszystko - poprawne zgłoszenie, 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 z przeglądarki

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

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

    return <html><body><h1>Coś poszło nie tak</h1></body></html>;
}

Vercel

Gdy RAY_ENVIRONMENT i RAY_RELEASE nie są ustawione, integracja bierze VERCEL_ENV jako środowisko i VERCEL_GIT_COMMIT_SHA jako wersję, więc deployment typu preview nie zgłasza się jako produkcja.

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.