Konfiguration - Node.js

Wissenswerte Optionen

Umgebungen

Jede Umgebung sollte unter einem eindeutigen Namen berichten - production, staging, preview. Der Name ist eine Spalte im Panel und ein Filter in der Fehlerliste; ohne ihn sieht ein Produktionsausfall genauso aus wie ein Fehler, den jemand im Test ausgelöst hat. Lass die lokale Umgebung ohne Zugangsdaten: ohne Token und Schlüssel lädt die Integration und bleibt still - ein eigener Schalter ist nicht nötig.

Wann Ereignisse hinausgehen

Ein Besucher wartet nie auf den Monitoring-Dienst. report() reiht einen Versand ein, ohne auf ihn zu warten, und hält eine Referenz auf das Promise, damit der Prozess nicht mittendrin beendet wird:

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

Die Framework-Adapter rufen das auf einem Ereignis auf, das erst nach dem Senden der Antwort feuert. Die Warteschlange hält höchstens 50 gleichzeitige Meldungen für den gesamten Prozess; alles darüber wird stillschweigend verworfen, ohne Log-Eintrag. sampleRate und tracesSampleRate entscheiden, welcher Anteil der Ereignisse überhaupt dorthin gelangt: 1 sendet immer, 0 nie, ein Wert dazwischen wird pro Aufruf unabhängig ausgewürfelt. Standardmäßig gehen Fehler vollständig hinaus, Transaktionen gar nicht.

Die Express- und Fastify-Adapter

Beide Adapter benennen Transaktionen nach dem Routenmuster, nicht der konkreten Adresse - GET /orders/:id, nicht GET /orders/8123. Standardmäßig lassen sie /health und /metrics aus (ignorePaths), melden nur 5xx-Antworten (shouldReport), entfernen Authorization, Cookie und X-Api-Key aus den Headern und lesen die IP-Adresse aus X-Forwarded-For oder X-Real-IP.

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

const app = express();

app.use(rayRequestHandler(ray));      // vor den Routen
// ... Routen ...
app.use(rayErrorHandler(ray));        // nach den Routen

rayRequestHandler öffnet eine Transaktion und meldet sie beim finish-Ereignis. rayErrorHandler meldet den Fehler und reicht ihn weiter - deine Fehlerseite rendert also trotzdem.

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

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

Das Fastify-Gegenstück zu finish ist onResponse - Transaktionen von dort, Fehler aus onError.

Browserfehler

Ein Browser kann sich nicht direkt bei DockRay authentifizieren. Eine Meldung, die eine deiner Routen erreicht hat, gibst du so weiter:

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 });
});

Die Nutzlast ist nicht vertrauenswürdig: unerkannte Felder werden verworfen, jeder String auf 1 KB gekürzt, der Stack auf 50 Frames, und alles, was sich nicht in ein Ereignis verwandeln lässt, liefert false. Der Umschlag - ID, Zeitstempel, Umgebung, Release - wird hier, auf dem Server, ausgefüllt, ein Browser wählt also nie, in welcher Umgebung seine Fehler landen. Der Kollektor auf der Seite ist ein eigener Einstiegspunkt, @dockcodes/dock-ray/browser; die Schranken des Endpunkts schreibst du selbst, genau wie die mitgelieferten CMS-Integrationen.

Den privaten Schlüssel schützen

Der private Schlüssel ist ein Projektgeheimnis, keine Kennung. Bewahre ihn in Umgebungsvariablen, in einem Secret-Manager oder in der Serverkonfiguration auf - niemals im Repository, in Logs, auf einem Screenshot oder in Code, der an den Browser geht. Ein Projekt kann mehrere Schlüssel haben, deshalb sollten Produktion und Staging je eigene bekommen: jeder lässt sich einzeln widerrufen, ohne die übrigen zu unterbrechen. Der Verdacht, dass ein Schlüssel abgeflossen ist, genügt, um ihn zu widerrufen und einen neuen zu erzeugen.