PathruleProtocollo e collector
Il protocollo Signals che un collector riceve (envelope, item, limiti di dimensione), come l'SDK interpreta le risposte del collector e ritenta, e come eseguire un tuo collector HTTP in modalità Standalone.
In questa pagina
In modalità Standalone l'SDK invia i dati a un collector HTTP gestito da te. Questa pagina descrive cosa riceve quel collector e come deve rispondere. Pathrule Local e Pathrule Cloud usano lo stesso protocollo, quindi nulla di quanto segue cambia quando passi da una destinazione all'altra.
L'envelope
Il protocollo è alla versione 1. L'SDK invia un envelope per ogni POST come application/json; il beacon inviato mentre una pagina viene chiusa usa text/plain. Un envelope occupa al massimo 32.768 byte e contiene al massimo 50 item.
| Campo | Cos'è |
|---|---|
schemaVersion | La versione del protocollo. |
id | Fino a 64 lettere, cifre, _ o -. Resta identico a ogni nuovo tentativo, così un collector può memorizzare un envelope una sola volta. |
key | La chiave del progetto. Solo per Cloud. |
environment | development, preview o production. |
release | L'identificativo della release, fino a 120 caratteri. |
connection | Il modo in cui l'SDK è connesso. |
items | I segnali e le dichiarazioni contenuti in questo envelope. |
Ogni item contiene type (signal o declaration), kind (error o event), fingerprint, countDelta, node (il percorso nel codice), flow, label, message e metadata. Le occorrenze ripetute vengono sommate in countDelta, quindi un collector deve contare usando questo campo, non il numero di item.
Risposte e nuovi tentativi
| Risposta | Cosa fa l'SDK |
|---|---|
2xx | Consegna riuscita. |
401, 403 | Smette di inviare in modo definitivo. |
408, 429, 5xx | Ritenta. |
Qualsiasi altro 4xx | Scarta il batch. |
I nuovi tentativi avvengono dopo 1, 5 e 15 minuti, al massimo 4 tentativi, e l'SDK tiene in attesa al massimo 20 envelope. Un header Retry-After viene interpretato come numero di secondi.
Eseguire un tuo collector
Un collector fa tre cose: autentica la richiesta, convalida l'envelope e lo memorizza o lo inoltra.
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 });
Passa requireKey: false quando ti autentichi in altro modo, per esempio con l'header bearer descritto nella guida rapida, e passa la dimensione grezza in modo che il limite di dimensione venga applicato. Poi:
- Memorizza un envelope una sola volta per ogni
id; i nuovi tentativi lo riutilizzano. - Raggruppa gli item per ambiente, tipo e fingerprint, come fa Pathrule.
- Rispondi
2xxnon appena l'envelope è al sicuro, e401o403solo quando il client deve fermarsi.