Instalacja - Next.js

Zanim zaczniesz, utwórz projekt w panelu DockRay. W jego ustawieniach znajdziesz token projektu - publiczny identyfikator, który wchodzi do adresu endpointu - a w zakładce Klucze API wygenerujesz klucz prywatny. Klucz jest pokazywany tylko raz, w momencie generowania: w bazie DockRay leży wyłącznie jego skrót. Jeżeli nie masz jeszcze projektu, zacznij od zakładania konta i pierwszego projektu.

Wymagania

• Next.js 14 lub 15, App Router albo Pages Router,
• Node.js 18 lub nowszy - integracja korzysta z wbudowanego fetch,
• npm.

Instalacja paczki

npm install @dockcodes/dock-ray-next

Poświadczenia

RAY_TOKEN=token-projektu
RAY_PRIVATE_KEY=klucz-prywatny-projektu
RAY_URL=https://dockray.io
RAY_TRACES_SAMPLE_RATE=0.2

RAY_PRIVATE_KEY nie może dostać przedrostka NEXT_PUBLIC_ - i to nie jest kwestia stylu. Next.js wkleja każdą zmienną z tym przedrostkiem wprost do paczki wysyłanej do przeglądarki, więc klucz prywatny stałby się publiczny w chwili builda. Bez RAY_TOKEN i RAY_PRIVATE_KEY integracja jest bezczynna - żadnych żądań, żadnych błędów - więc można ją wpiąć raz i nie owijać w warunek.

Raportowanie błędów serwera

W instrumentation.ts w katalogu głównym projektu:

import { initRay, rayRequestError } from '@dockcodes/dock-ray-next';

export function register() {
    initRay();
}

export const onRequestError = rayRequestError();

onRequestError to jedyny hook, który widzi każdy błąd przechwycony przez Next - z Server Components, Route Handlers, Server Actions i renderowania strumieniowego. Next wywołuje go już po tym, jak odpowiedź się nie powiodła, więc raportowanie nigdy nie opóźnia żądania. Każde zgłoszenie jest otagowane kontekstem trasy (router, route, route_type, render_source), dzięki czemu w panelu widać, z której części aplikacji błąd naprawdę przyszedł.

Middleware i Edge Runtime

Next zawsze buduje middleware jako bundle brzegowy, a bundle brzegowy nie potrafi rozwiązać node:fs ani node:zlib. Middleware i trasy uruchamiane na Edge importują osobny punkt wejścia:

import { initRay, withRayMiddleware } from '@dockcodes/dock-ray-next/edge';

initRay();

export const middleware = withRayMiddleware(async (request) => {
    // ...
});

Zdarzenia z Edge tracą kontekst źródeł w stosie wywołań i kompresję gzip - poza tym nic się nie zmienia. Wrapper brzegowy czeka na wysłanie raportu, zamiast wystrzelić go i zapomnieć: wywołanie na Edge bywa zamrażane w chwili, gdy funkcja zwraca wynik, więc niedoczekane wysłanie mogłoby nigdy nie wyjść.

Pages Router i trasy API

onRequestError obejmuje App Router. Dla Pages Router albo tam, gdzie zależy Ci na jawnym oznaczeniu błędu jako własnego, użyj wrappera:

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

export default withRay(async function handler(req, res) {
    const order = await processOrder(req.body);

    res.status(200).json({ success: true, order });
});

withRay raportuje i rzuca wyjątek dalej - nigdy go nie połyka, więc Twoja własna obsługa błędów nadal działa.

Pierwszy test

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

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

Wywołaj to z tymczasowej trasy albo Server Action na środowisku testowym. Komunikat powinien pojawić się w panelu w sekcji Błędy projektu wskazanego przez token.