Osservabilità
Log consegne in Console, replay manuale, correlazione con traceId, metriche da monitorare e runbook per l on-call.
Un'integrazione senza osservabilità è un'integrazione che scoprirai rotta dal cliente. Questa pagina descrive gli strumenti disponibili in Console e le metriche da presidiare lato automazione.
Log consegne
Il registro conserva 30 giorni di consegne per ogni endpoint, con richiesta e risposta complete.
Campi disponibili
| Campo | Descrizione |
|---|---|
| Data e ora | Istante del tentativo, fuso Europe/Rome |
| Evento | Tipo di evento, es. session.handover.requested |
| ID evento | Campo id del payload, stabile tra i tentativi |
| ID consegna | Valore di X-BP-Delivery, diverso per ogni replay |
| Endpoint | URL di destinazione |
| Tentativo | Numero da 1 a 5 |
| Stato | Riuscita, In corso, Fallita, Dead letter |
| Codice risposta | Codice HTTP restituito dal tuo endpoint |
| Tempo di risposta | Millisecondi fino alla risposta completa |
| Motivo del fallimento | timeout, connessione rifiutata, TLS non valido, redirect, codice non 2xx |
| Header inviati | Elenco completo, con la firma |
| Corpo inviato | JSON grezzo, scaricabile byte per byte |
| Corpo ricevuto | Primi 4 KB della risposta del tuo endpoint |
| traceId | Identificativo di correlazione con la conversazione |
Filtri
| Filtro | Uso tipico |
|---|---|
| Stato | Fallita per l'analisi degli incidenti |
| Tipo di evento | Isolare un singolo flusso |
| Endpoint | Confrontare produzione e collaudo |
| Intervallo temporale | Restringere alla finestra dell'incidente |
| Codice risposta | Distinguere 401 (firma) da 500 (bug applicativo) |
| ID evento | Seguire tutti i tentativi dello stesso evento |
| traceId | Ricostruire l'intera catena da una conversazione |
Scarica il corpo grezzo
Il pulsante Scarica corpo grezzo salva i byte esatti firmati. È l'unico modo affidabile per riprodurre offline una verifica di firma fallita. Vedi cURL.
Replay manuale
Filtra le consegne fallite
Imposta Stato su Fallita e l'intervallo temporale dell'incidente. Verifica che il
problema a valle sia stato risolto prima di procedere.
Verifica una singola consegna
Apri la prima consegna e clicca Riprova. Attendi l'esito. Se risponde 2xx, il problema è
risolto.
Rilancia in blocco
Seleziona le consegne dalla tabella e clicca Riprova selezione. Il rilancio avviene con una frequenza limitata per non saturare il tuo endpoint.
Controlla i duplicati
Il replay genera un nuovo X-BP-Delivery. Verifica nel tuo sistema che la deduplica sul
campo id dell'evento abbia funzionato e che non siano stati creati record doppi.
Ordine del replay
Il rilancio in blocco non garantisce l'ordine cronologico. Se il tuo flusso è sensibile alla
sequenza (creazione seguita da aggiornamento), rilancia in ordine di createdAt oppure
affidati al riordino difensivo descritto in
Modello di integrazione.
Correlazione con traceId
Ogni evento porta data.traceId. Lo stesso valore compare:
- nel dettaglio della sessione in Console;
- nei log consegne;
- negli audit log del tenant.
Propaga il traceId in tutti i log del tuo sistema. Diventa la chiave per ricostruire un
incidente end-to-end.
const traceId = event.data?.traceId ?? 'sconosciuto';
logger.info('Evento ricevuto', {
traceId,
eventId: event.id,
deliveryId,
eventType: event.event,
});
await erp.createOrder(record, {
headers: { 'X-Correlation-Id': traceId },
});
logger.info('Ordine creato', { traceId, orderNumber });Con un traceId puoi rispondere in pochi minuti a domande come: la conversazione delle 09:26
ha generato l'ordine nell'ERP?
Allarmi sui fallimenti ripetuti
| Regola | Soglia consigliata | Destinatario |
|---|---|---|
| Consegne fallite consecutive | 3 | Canale del team di automazione |
| Tasso di fallimento su 15 minuti | oltre il 5% | Canale on-call |
| Consegna in dead letter | qualsiasi | Canale on-call |
| Endpoint disattivato automaticamente | qualsiasi | Responsabile dell'integrazione |
| Tempo di risposta p95 | oltre 3 secondi | Canale del team di automazione |
| Chiave API in scadenza | 30 giorni | Amministratore tenant |
Puoi anche sottoscrivere l'evento webhook.delivery.failed su un endpoint di sola allerta,
separato da quello di produzione, per instradare gli allarmi verso il tuo sistema di
monitoraggio.
Metriche lato automazione
Blu Pantheon vede solo l'esito della consegna. La salute del processo è visibile solo dal tuo lato. Presidia almeno queste metriche.
Ricezione
| Metrica | Descrizione | Soglia di allarme |
|---|---|---|
webhook_ricevuti_totale | Contatore per tipo di evento | Calo oltre il 50% rispetto alla media oraria |
webhook_rifiutati_totale | Contatore per motivo di rifiuto | Qualsiasi valore diverso da zero |
webhook_latenza_risposta_ms | Istogramma del tempo di risposta | p95 oltre 500 ms |
webhook_duplicati_totale | Consegne scartate dalla deduplica | Crescita anomala indica ritentativi |
Coda
| Metrica | Descrizione | Soglia di allarme |
|---|---|---|
coda_profondita | Messaggi in attesa | Oltre 100, oppure crescita continua per 15 minuti |
coda_eta_messaggio_piu_vecchio_s | Età del messaggio più vecchio | Oltre 900 secondi |
coda_dead_letter_totale | Messaggi non elaborabili | Qualsiasi valore diverso da zero |
coda_tasso_ingresso | Messaggi al minuto in ingresso | Confronto con il tasso di uscita |
coda_tasso_uscita | Messaggi al minuto elaborati | Inferiore al tasso di ingresso per oltre 10 minuti |
Elaborazione
| Metrica | Descrizione | Soglia di allarme |
|---|---|---|
elaborazione_durata_s | Istogramma per tipo di evento | p95 oltre il doppio della mediana storica |
elaborazione_errori_totale | Contatore per tipo di errore | Tasso di errore oltre l'1% |
robot_disponibili | Bot Runner o worker liberi | Zero per oltre 5 minuti |
gestionale_latenza_s | Tempo di risposta del sistema a valle | p95 oltre 30 secondi |
Chiamate inbound
| Metrica | Descrizione | Soglia di allarme |
|---|---|---|
api_richieste_totale | Contatore per endpoint e stato | — |
api_errori_4xx_totale | Errori client | Qualsiasi 401 o 403 |
api_errori_5xx_totale | Errori server | Tasso oltre lo 0,5% |
api_rate_limit_residuo | Valore di X-RateLimit-Remaining | Sotto il 10% del limite |
api_latenza_ms | Istogramma | p95 oltre 1000 ms |
Il segnale più importante
Se puoi monitorare una sola metrica, scegli l'età del messaggio più vecchio in coda. Cresce in presenza di qualsiasi problema a valle e ha una soglia interpretabile senza contesto aggiuntivo.
Dashboard consigliata
Organizza la dashboard su tre righe:
| Riga | Contenuto | Domanda a cui risponde |
|---|---|---|
| Ingresso | Webhook ricevuti per evento, rifiuti, latenza di risposta | Blu Pantheon riesce a consegnarci? |
| Coda | Profondità, età del più vecchio, tassi di ingresso e uscita | Stiamo tenendo il passo? |
| Uscita | Chiamate API per stato, latenza del gestionale, errori | Il lavoro arriva a destinazione? |
Aggiungi un pannello con gli ultimi 20 traceId in errore, cliccabili verso i log applicativi.
Runbook per l'on-call
| Sintomo | Verifica immediata | Azione | Escalation |
|---|---|---|---|
| Nessun webhook da oltre 30 minuti | Log consegne in Console: ci sono tentativi? | Se non ci sono tentativi, controlla che l'endpoint sia Attivo e che gli eventi siano sottoscritti | Supporto Blu Pantheon dopo 1 ora |
Consegne fallite con 401 | Motivo del rifiuto nei tuoi log | Verifica il segreto webhook; controlla se è in corso una rotazione | Responsabile integrazione, subito |
Consegne fallite con timeout | Tempo di risposta nei log consegne | Sposta l'elaborazione in coda; verifica il carico del server | Team applicativo entro 30 minuti |
Consegne fallite con TLS non valido | openssl s_client sull'endpoint | Rinnova il certificato; verifica la catena intermedia | Team infrastruttura, subito |
| Coda in crescita continua | Robot disponibili, latenza del gestionale | Aumenta la concorrenza o riavvia i runner bloccati | Team RPA entro 15 minuti |
| Dead letter non vuota | Motivo dell'ultimo tentativo | Correggi la causa, poi replay dalla Console | Responsabile integrazione entro 4 ore |
429 frequenti sulle API | X-RateLimit-Remaining nei log | Riduci il parallelismo, aggiungi cache locale | Supporto Blu Pantheon se persiste |
| Record duplicati nel gestionale | Log della deduplica | Verifica il salvataggio di X-BP-Delivery e id; correggi i duplicati | Team applicativo entro 2 ore |
| Dati errati nel gestionale | traceId del record errato | Correggi la mappatura dei campi; rielabora dal replay | Responsabile funzionale |
| Robot bloccato su schermata inattesa | Screenshot dell'orchestratore | Riavvia il runner, aggiorna il selettore | Team RPA entro 1 ora |
Procedura di indagine standard
Delimita l'intervallo
Determina l'ora del primo e dell'ultimo evento anomalo. Filtra i log consegne su quella finestra.
Stabilisci il lato del problema
Se i log consegne mostrano 2xx, il problema è dopo la ricezione: coda, robot o gestionale.
Se mostrano errori, il problema è nel tuo endpoint o nella rete.
Isola un caso singolo
Prendi un traceId rappresentativo e segui l'intero percorso: log consegne, log del listener,
coda, log del robot, record nel gestionale.
Verifica l'ipotesi
Riproduci il caso in collaudo con lo stesso corpo grezzo scaricato dalla Console.
Applica il rimedio e rielabora
Correggi la causa, poi rilancia dalla Console le consegne dell'intervallo. Verifica che la deduplica impedisca i duplicati.
Registra l'incidente
Annota causa, rimedio e durata. Se il budget di errore concordato è stato superato, pianifica un'azione correttiva strutturale.
Conservazione dei dati
| Dato | Ritenzione | Note |
|---|---|---|
| Log consegne | 30 giorni | Include corpi di richiesta e risposta |
| Dead letter | 30 giorni | Replay disponibile per tutto il periodo |
| Audit log delle chiavi API | 24 mesi | Creazione, rotazione, revoca |
| Deduplica lato consumatore | almeno 7 giorni | Consigliato 30 giorni se usi il replay |