Instalacja - Node.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

• Node.js 18 lub nowszy - pakiet korzysta z wbudowanego fetch i nie ma żadnych zależności,
• możliwość wykonywania połączeń wychodzących HTTPS.

Pakiet jest integracją serwerową. Nie ma i nie będzie miał wariantu przeglądarkowego - uwierzytelnienie w panelu wymaga klucza prywatnego projektu, a ten musi zostać na serwerze. Błędy z przeglądarki przechodzą przez Twoją własną aplikację, nie przez tę paczkę bezpośrednio.

Instalacja

npm install @dockcodes/dock-ray

Runtime brzegowy

Główne wejście pakietu importuje node:fs, node:os i node:zlib, których bundel brzegowy - middleware Next.js, Cloudflare Workers, Vercel Edge - nie potrafi rozwiązać. Tam, gdzie kod działa poza pełnym procesem Node, użyj osobnego wejścia:

import { DockRayClient } from '@dockcodes/dock-ray/edge';

API jest identyczne. Zdarzenia z tego wejścia tracą kontekst źródła w stosie wywołań i kompresję gzip, bo runtime nie ma systemu plików ani zlib - poza tym nic się nie zmienia.

Utworzenie klienta

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

const ray = new DockRayClient({
    token: process.env.RAY_TOKEN,
    privateKey: process.env.RAY_PRIVATE_KEY,
    environment: process.env.NODE_ENV,
    release: process.env.APP_VERSION,
});

Bez tokenu i klucza konstruktor niczego nie rzuca - ray.enabled zwraca false, a każde wywołanie raportujące zwraca false bez próby połączenia z siecią. Pakiet sam nie czyta żadnych zmiennych środowiskowych - to Twój kod, jak w przykładzie powyżej, decyduje, skąd wziąć token i klucz, więc klienta można tworzyć bezwarunkowo i zostawić poświadczenia poza środowiskiem lokalnym.

Raportowanie

try {
    await settle(order);
} catch (error) {
    await ray.captureException(error);
}

Pierwszy test

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

Komunikat powinien pojawić się w panelu w sekcji Błędy projektu wskazanego przez token.