Installation - Node.js

Erstelle zuerst ein Projekt im DockRay-Panel. In seinen Einstellungen findest du den Projekt-Token - die öffentliche Kennung, die in die Ingest-URL eingeht - und im Tab API-Schlüssel erzeugst du einen privaten Schlüssel. Der Schlüssel wird nur einmal angezeigt, beim Erzeugen: DockRay speichert lediglich seinen Hash. Wenn noch kein Projekt existiert, beginne mit Erste Schritte.

Voraussetzungen

• Node.js 18 oder neuer - das Paket nutzt das eingebaute fetch und hat keine Abhängigkeiten,
• ausgehende HTTPS-Verbindungen erlaubt.

Das Paket ist eine serverseitige Integration. Es gibt keine Browser-Variante und wird auch keine geben - die Authentifizierung beim Panel braucht den privaten Schlüssel des Projekts, und der muss auf dem Server bleiben. Browserfehler laufen stattdessen über deine eigene Anwendung, nicht direkt über dieses Paket.

Installation

npm install @dockcodes/dock-ray

Edge-Runtimes

Der Haupteinstiegspunkt des Pakets importiert node:fs, node:os und node:zlib, die ein Edge-Bundle - Next.js-Middleware, Cloudflare Workers, Vercel Edge - nicht auflösen kann. Läuft der Code außerhalb eines vollständigen Node-Prozesses, importiere stattdessen den eigenen Einstiegspunkt:

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

Die API ist identisch. Ereignisse aus diesem Einstiegspunkt verlieren den Quellkontext im Stacktrace und die gzip-Kompression, weil die Runtime kein Dateisystem und kein zlib hat - sonst ändert sich nichts.

Client erzeugen

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

Fehlen Token und Schlüssel, wirft der Konstruktor nichts - ray.enabled liefert false, und jeder Reporting-Aufruf löst zu false auf, ohne einen Verbindungsversuch. Das Paket liest selbst keine Umgebungsvariable - dein eigener Code entscheidet, wie im Beispiel oben, woher Token und Schlüssel kommen, sodass sich der Client bedingungslos erzeugen lässt und die Zugangsdaten einfach aus der lokalen Umgebung bleiben.

Melden

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

Der erste Test

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

Die Meldung sollte im Panel unter Fehler des Projekts erscheinen, auf das der Token zeigt.