Konfiguracja - Node.js

Opcje, które warto znać

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

Kiedy zdarzenia wychodzą

Odwiedzający nigdy nie czeka na monitoring. report() kolejkuje wysyłkę bez czekania na jej wynik, trzymając referencję do obietnicy, żeby proces nie zakończył się w trakcie lotu:

ray.report(ray.captureException(error));

Adaptery frameworków wywołują to na zdarzeniu, które odpala się dopiero po wysłaniu odpowiedzi. Kolejka trzyma najwyżej 50 równoległych zgłoszeń na cały proces; nadwyżka jest odrzucana po cichu, bez wpisu w logu. sampleRate i tracesSampleRate decydują, jaki ułamek zdarzeń w ogóle tam trafia: 1 wysyła zawsze, 0 nigdy, wartość pośrednia losuje niezależnie przy każdym wywołaniu. Domyślnie błędy idą w komplecie, a transakcje wcale.

Adaptery Express i Fastify

Oba adaptery nazywają transakcje wzorcem trasy, a nie konkretnym adresem - 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. Domyślnie pomijają /health i /metrics (ignorePaths), raportują tylko odpowiedzi 5xx (shouldReport) i wycinają Authorization, Cookie oraz X-Api-Key z raportowanych nagłówków. Adres IP odwiedzającego czytają z X-Forwarded-For albo X-Real-IP, zanim sięgną po adres gniazda.

import express from 'express';
import { rayRequestHandler, rayErrorHandler } from '@dockcodes/dock-ray/express';

const app = express();

app.use(rayRequestHandler(ray));      // przed trasami
// ... trasy ...
app.use(rayErrorHandler(ray));        // po trasach

rayRequestHandler otwiera transakcję i raportuje ją przy zdarzeniu finish odpowiedzi. rayErrorHandler zgłasza błąd i przekazuje go dalej - nigdy go nie połyka, więc Twoja własna strona błędu nadal się wyrenderuje.

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

await fastify.register(rayPlugin, { client: ray });

Odpowiednikiem finish jest tu hak onResponse - transakcje są raportowane z niego, a błędy z onError.

Błędy przeglądarki

Przeglądarka nie może uwierzytelnić się w DockRayu wprost - klucz prywatny musi zostać na serwerze. Zgłoszenie, które dotarło do jednej z Twoich tras, przekazujesz dalej:

app.post('/api/ray/browser', async (req, res) => {
    ray.report(ray.captureBrowserReport(req.body, {
        pageUrl: req.headers.referer,
        userAgent: req.headers['user-agent'],
    }));

    res.status(202).json({ success: true });
});

Ładunek jest niezaufany: nierozpoznane pola są odrzucane, każdy ciąg przycięty do 1 KB, stos wywołań do 50 ramek, a co nie da się zamienić w zdarzenie, zwraca false. Kopertę - identyfikator, znacznik czasu, środowisko, wersję - wypełnia ten kod po stronie serwera, więc przeglądarka nigdy nie wybiera środowiska swoich błędów. Kolektor strony to osobne wejście, @dockcodes/dock-ray/browser; bramki endpointu piszesz sam, jak w integracjach CMS.

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.