Überprüfung und typische Probleme - Node.js

Ein kontrolliertes Ereignis

await ray.captureMessage('DockRay-Kontrollmeldung');

Reporting-Methoden liefern ein Promise - in einem Skript, das gleich nach dem Aufruf endet, stelle ihm await voran oder wickle es in ray.report() ein, sonst kann der Prozess herunterfahren, bevor die Anfrage hinausgeht.

Typische Probleme

ray.enabled ist false, obwohl die Variablen gesetzt sind

Der Client liest process.env nie selbst - Zugangsdaten erreichen den Konstruktor immer ausdrücklich, wie in den Beispielen dieses Abschnitts. Prüfe, ob token und privateKey wirklich als nicht leere Strings angekommen sind; ein leerer String zählt genauso wie gar kein Wert.

Der Build lässt sich in einer Edge-Runtime oder auf Cloudflare Workers nicht kompilieren

Das Symptom ist meist ein Bundler-Fehler in der Art „Module not found: Can't resolve 'node:fs'". Der Haupteinstiegspunkt des Pakets importiert node:fs, node:os und node:zlib, die ein solches Bundle nicht auflösen kann. Importiere stattdessen @dockcodes/dock-ray/edge - die API bleibt gleich, es verschwinden nur der Quellkontext im Stacktrace und die gzip-Kompression.

installGlobalHandlers() tut nichts, bis du es aufrufst

Das Abfangen nicht abgefangener Prozessfehler ist standardmäßig aus - es muss bewusst eingeschaltet werden, weil es ändert, wie der Prozess bei einem fatalen Fehler endet. Nach dem Aufruf von ray.installGlobalHandlers() endet eine gemeldete uncaughtException mit einem Aufruf von process.exit(1), sofern du nicht { exitOnUncaught: false } übergibst. Eine unhandledRejection wird nur gemeldet und beendet den Prozess nicht.

Unter starker Last verschwinden einzelne Ereignisse

Die Warteschlange von report() hält höchstens 50 gleichzeitige Meldungen für den gesamten Prozess; alles darüber wird ohne Spur im Log verworfen. Prüfe auch sampleRate, falls sie gesenkt wurde - sie steht standardmäßig auf 1 und sendet alles.

Transaktionen zerfallen in tausende verschiedene Zeilen

Der Name einer Transaktion stammt aus dem beim Router registrierten Routenmuster (req.route.path in Express, routerPath in Fastify). Läuft der Adapter auf einer Anfrage, die nie einen registrierten Handler erreicht hat - eine 404-Antwort, ein vor dem Router platziertes Middleware -, fehlt das Muster, und der Name fällt auf den rohen Pfad der Adresse zurück, sodass jede eigene Adresse zu einer eigenen Zeile wird.

4xx-Codes erreichen das Panel nicht als Fehler

Das ist das erwartete Verhalten des Standard-shouldReport: Es werden nur 5xx-Antworten gemeldet, weil ein 4xx meist ein Fehler des Aufrufers ist, kein Versagen der Anwendung. Übergib dem Adapter eine eigene shouldReport-Funktion, um das zu ändern.

Das Panel antwortet 200, aber es gibt kein Ereignis

Eine Antwort 200 {"success": false} bedeutet, dass das Konto sein monatliches Fehlerkontingent aufgebraucht hat. Die Integration behandelt das nicht als Störung - zu Recht. Das Kontingent siehst du im Konto-Dashboard; bis zum Monatsende wird es aus der erfassten Nutzung berechnet, Fehler zu löschen setzt es also nicht zurück.

Es funktioniert weiterhin nicht

Arbeite die Checkliste zur Fehlerbehebung durch, und wenn das nicht hilft, schreib uns. Nenne den Projektnamen, die Version der Integration und ungefähr die Uhrzeit des Tests: das verkürzt den Weg zur Antwort.