PathruleProtokoll und Collectors
Das Signals-Protokoll, das ein Collector empfängt (Envelope, Items, Größenlimits), wie das SDK Collector-Antworten auswertet und Wiederholungen ausführt und wie du im Standalone-Modus einen eigenen HTTP-Collector betreibst.
Im Standalone-Modus sendet das SDK an einen HTTP-Collector, den du selbst betreibst. Diese Seite beschreibt, was dieser Collector empfängt und wie er antworten sollte. Pathrule Local und Pathrule Cloud sprechen dasselbe Protokoll, daher ändert sich hier nichts, wenn du das Ziel wechselst.
Das Envelope
Das Protokoll liegt in Version 1 vor. Das SDK sendet pro POST ein Envelope als application/json; der Beacon, der beim Entladen einer Seite gesendet wird, verwendet text/plain. Ein Envelope ist höchstens 32.768 Bytes groß und enthält höchstens 50 Items.
| Feld | Bedeutung |
|---|---|
schemaVersion | Die Protokollversion. |
id | Bis zu 64 Buchstaben, Ziffern, _ oder -. Bei jeder Wiederholung gleich, sodass ein Collector ein Envelope nur einmal speichern muss. |
key | Der Projektschlüssel. Nur für Cloud. |
environment | development, preview oder production. |
release | Die Release-Kennung, bis zu 120 Zeichen. |
connection | Wie das SDK verbunden ist. |
items | Die Signale und Deklarationen in diesem Envelope. |
Jedes Item hat type (signal oder declaration), kind (error oder event), fingerprint, countDelta, node (den Codepfad), flow, label, message und metadata. Wiederholte Vorkommen werden in countDelta aufsummiert, ein Collector zählt also über diesen Wert und nicht über die Anzahl der Items.
Antworten und Wiederholungen
| Antwort | Verhalten des SDK |
|---|---|
2xx | Zugestellt. |
401, 403 | Stellt das Senden dauerhaft ein. |
408, 429, 5xx | Wiederholt. |
Jedes andere 4xx | Verwirft den Batch. |
Wiederholungen erfolgen nach 1, 5 und 15 Minuten, mit höchstens 4 Versuchen, und das SDK hält höchstens 20 Envelopes in der Warteschlange. Ein Retry-After-Header wird als Anzahl Sekunden ausgewertet.
Eigenen Collector betreiben
Ein Collector erledigt drei Dinge: Er authentifiziert die Anfrage, validiert das Envelope und speichert oder leitet es weiter.
import { normalizeEnvelope } from "@pathrule/signals/protocol";
// In your POST handler, after checking your own Authorization header:
const envelope = normalizeEnvelope(body, { requireKey: false, bytes: rawBody.length });
Übergib requireKey: false, wenn du auf anderem Weg authentifizierst, etwa über den Bearer-Header aus dem Schnellstart, und übergib die Rohgröße, damit das Größenlimit durchgesetzt wird. Danach:
- Speichere ein Envelope einmal pro
id; Wiederholungen verwenden sie erneut. - Gruppiere Items nach Umgebung, Art und Fingerprint, genau wie Pathrule.
- Antworte mit
2xx, sobald das Envelope sicher abgelegt ist, und mit401oder403nur dann, wenn der Client das Senden einstellen soll.