PathruleProtocole et collecteurs
Le protocole Signals reçu par un collecteur (enveloppe, éléments, limites de taille), la façon dont le SDK interprète les réponses du collecteur et réessaie, et comment faire tourner votre propre collecteur HTTP en mode Standalone.
En mode Standalone, le SDK envoie ses données à un collecteur HTTP que vous hébergez. Cette page décrit ce que reçoit ce collecteur et la manière dont il doit répondre. Pathrule Local et Pathrule Cloud parlent le même protocole : rien de ce qui suit ne change quand vous changez de destination.
L'enveloppe
Le protocole est en version 1. Le SDK envoie une enveloppe par POST en application/json ; le beacon envoyé pendant le déchargement d'une page utilise text/plain. Une enveloppe fait au maximum 32 768 octets et contient au plus 50 éléments.
| Champ | Description |
|---|---|
schemaVersion | La version du protocole. |
id | Jusqu'à 64 lettres, chiffres, _ ou -. Identique à chaque nouvelle tentative, ce qui permet au collecteur de ne stocker une enveloppe qu'une seule fois. |
key | La clé du projet. Cloud uniquement. |
environment | development, preview ou production. |
release | L'identifiant de la release, jusqu'à 120 caractères. |
connection | Le mode de connexion du SDK. |
items | Les signaux et déclarations contenus dans cette enveloppe. |
Chaque élément comporte type (signal ou declaration), kind (error ou event), fingerprint, countDelta, node (le chemin dans le code), flow, label, message et metadata. Les occurrences répétées sont additionnées dans countDelta : un collecteur compte donc avec ce champ, et non en comptant les éléments.
Réponses et nouvelles tentatives
| Réponse | Comportement du SDK |
|---|---|
2xx | Livré. |
401, 403 | Arrête définitivement l'envoi. |
408, 429, 5xx | Réessaie. |
Tout autre 4xx | Abandonne le lot. |
Les nouvelles tentatives ont lieu après 1, 5 et 15 minutes, avec 4 tentatives au maximum, et le SDK conserve au plus 20 enveloppes en attente. Un en-tête Retry-After est interprété comme un nombre de secondes.
Faire tourner votre propre collecteur
Un collecteur fait trois choses : authentifier la requête, valider l'enveloppe, puis la stocker ou la transmettre.
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 });
Passez requireKey: false si vous authentifiez autrement, par exemple avec l'en-tête bearer du guide de démarrage rapide, et transmettez la taille brute pour que la limite de taille soit appliquée. Ensuite :
- Stockez une enveloppe une seule fois par
id; les nouvelles tentatives réutilisent le même. - Regroupez les éléments par environnement, type et empreinte, comme le fait Pathrule.
- Répondez
2xxdès que l'enveloppe est en sécurité, et401ou403uniquement lorsque le client doit cesser d'envoyer.