Signals-Schnellstart

Auf dieser Seite bindest du das Signals SDK in eine App ein, legst fest, wohin die Events gehen, und meldest die Fehler und Events, die Signals gruppiert und verifiziert. Das SDK ist in jedem Modus dasselbe; nur das Ziel ändert sich.

SDK einbinden

npm install @pathrule/signals

Das SDK ist @pathrule/signals und steht unter der Lizenz Apache-2.0. Es läuft auf Node 18 oder neuer und in aktuellen Browsern (ES2022 und fetch). Das öffentliche npm-Paket wird gerade veröffentlicht; den aktuellen Stand findest du in der Übersicht.

Initialisieren

import { pathrule, httpCollector } from "@pathrule/signals";

pathrule.init({
  destination: httpCollector({
    url: "https://collector.example.com/signals",
    headers: { Authorization: `Bearer ${process.env.SIGNALS_TOKEN}` },
  }),
  environment: "production",
  release: { version: "2.4.0", commit: process.env.GIT_SHA },
});

environment ist development, preview oder production.

Ziel wählen

Standalone, mit deinem eigenen Collector. httpCollector({ url, headers?, credentials? }) sendet Envelopes per POST an jeden Endpunkt, der das Signals-Protokoll spricht. Ein Pathrule-Konto ist dafür nicht nötig.

Pathrule Local. Lege einmalig einen lokalen Workspace im Projekt an und sende die Events dann an den Pathrule-Host auf deinem Rechner. Dieses Ziel gibt es nur für Node.

pathrule init --local

import { pathrule } from "@pathrule/signals";
import { pathruleLocal } from "@pathrule/signals/local";

pathrule.init({ destination: pathruleLocal(), environment: "development", release: "2.4.0" });

Pathrule Cloud. Erstelle einen Projektschlüssel und übergib ihn an das Cloud-Ziel. Schlüssel beginnen mit prs_, erlauben nur Schreibzugriff und dürfen bedenkenlos im Client-Code ausgeliefert werden. Wie du Schlüssel verwaltest, steht unter Cloud Signals.

import { pathrule, pathruleCloud } from "@pathrule/signals";

pathrule.init({
  destination: pathruleCloud({ key: process.env.PATHRULE_SIGNALS_KEY }),
  environment: "production",
  release: { version: "2.4.0", commit: process.env.GIT_SHA },
});

Ein eigenes Ziel ist jedes Objekt, das SignalsDestination implementiert.

Fehler und Events melden

try {
  await submitOrder(cart);
  pathrule.event("order placed", {
    node: "/apps/web/checkout",
    flow: "checkout",
    meta: { outcome: "success" },
  });
} catch (error) {
  pathrule.error(error, { node: "/apps/web/checkout", flow: "checkout" });
  throw error;
}

Das zweite Argument ist die Verknüpfung: node ist der Codepfad, zu dem das Event gehört, flow benennt den für Nutzer sichtbaren Flow, text ergänzt eine kurze Beschreibung und meta enthält Details. Ein Event mit meta.outcome: "success" im Flow einer Gruppe ist der Nachweis, mit dem sich ein Fix für diese Gruppe verifizieren lässt.

Release setzen

release ist ein Versionsstring, ein Objekt mit version, commit und deployment oder null. releaseFromEnvironment(process.env) liest den Wert aus gängigen Deployment-Variablen. Ohne Release-Identität kann Signals Events zwar weiterhin gruppieren, aber keinen Fix verifizieren: pathrule.status().verification meldet dann no_release.

Vor dem Prozessende flushen

const result = await pathrule.flush({ timeoutMs: 5000 });
// result: { outcome, delivered, pending, dropped }

flush() liefert nie ein abgelehntes Promise. Das Timeout beträgt standardmäßig 5 Sekunden, maximal 30. Im Browser sendet das SDK ausstehende Daten beim Verlassen der Seite per sendBeacon, unter Node flusht es bei beforeExit. In kurzlebigen Prozessen wie Serverless-Funktionen rufst du es selbst auf.

Konfiguration

pathrule.status() meldet, ob die Verifizierung ready, no_release oder inactive ist, und pathrule.reset() setzt den Client zurück.