Strumento di monitoraggio API: uptime, tempo di risposta e validazione da oltre 300 località

Il monitoraggio delle API REST assomiglia superficialmente al monitoraggio uptime, ma è un lavoro diverso. Un'API viene consumata da codice, non da persone, e il codice è spietato in modi in cui un browser non lo è. Un visitatore umano tollera una pagina che si visualizza in modo leggermente sbagliato; un'integrazione che riceve un campo del tipo sbagliato semplicemente si rompe. Quindi il monitoraggio API deve controllare più livelli di un semplice "il server ha risposto", e HostTracker li controlla in ordine, facendo fallire il controllo al primo che non regge.

I livelli da uno a tre sono ciò che ti offre un normale controllo uptime. Il quarto e il quinto sono ciò che lo rende monitoraggio API - e sono i livelli in cui vive davvero la maggior parte degli incidenti API reali.

Prima che qualcosa possa essere validato, il monitor deve effettuare la richiesta che la tua API si aspetta. L'intera superficie della richiesta è disponibile su un monitor API:

Il modo più espressivo per validare una risposta è scriverci delle regole. Ogni regola è una riga, le regole si combinano con AND, e un monitor può portarne fino a venti. Questo è il pacchetto di partenza verificato per un'API JSON:

status isOk
header("Content-Type") contains "json"
body.json.path("$.count") gt 0
time lt 5s

Quattro righe che insieme coprono i quattro livelli che contano: l'endpoint ha risposto con un 2xx, ha risposto con JSON invece che con una pagina di errore, il payload contiene un risultato reale invece che vuoto, e ha fatto tutto questo entro il budget. Regole singolarmente utili dello stesso catalogo includono body.json.path("$.status") eq "ok" per il verdetto di salute proprio dell'API, body.json.path("$.error") absent per un membro di errore che compare in una risposta altrimenti di successo, body.json.path("$.version") eq "2.4.1" per intercettare un rollback non voluto, redirects.count eq 0 per un endpoint che deve rispondere direttamente, e cert.days.left gt 14 per il certificato sulla stessa connessione.

Di cosa può parlare una regola

Le regole leggono soggetti dalla risposta e li confrontano. I soggetti coprono il codice di stato; il tempo di risposta totale e le sue componenti di connessione, TLS, DNS, intestazioni e corpo; il corpo grezzo insieme alla sua dimensione e a un suo hash; query strutturate nel payload come JSON, XML, HTML o YAML; le singole intestazioni della risposta; l'URL finale e quello originale e le loro parti; la catena di reindirizzamenti, passaggio per passaggio; i giorni rimanenti del certificato, l'autorità emittente e i nomi; il protocollo TLS e il cifrario negoziati; gli indirizzi restituiti dal DNS; e Set-Cookie. I confronti vanno dagli ovvi - uguale, minore di, maggiore di - fino a contains, startsWith, endsWith, matches per un'espressione regolare, containsAny e containsAll per un insieme, in per un elenco di valori accettabili, e exists, isNumber e unique.

Esiste anche un asse di rilevamento dei cambiamenti: una regola può confrontare il valore di questa esecuzione con quello dell'esecuzione precedente, così puoi verificare che un contatore non torni mai indietro o che un hash del corpo non sia cambiato - il tipo di regola che intercetta un rollback silenzioso o una modifica non autorizzata del contenuto, piuttosto che un'interruzione.

Accanto al linguaggio delle regole esiste un percorso più semplice, a valore singolo, che fa parte del monitoraggio API qui da molto tempo ed è spesso tutto ciò di cui un controllo ha bisogno. Indichi al monitor come analizzare il corpo, come selezionarne un valore, e cosa quel valore deve essere:

• Analizza come JSON, e il selettore è un'espressione JSONPath.
• Analizza come XML, e il selettore è un'espressione XPath - il che rende semplice controllare SOAP e altri servizi XML.
• Trattalo come testo semplice, e il selettore è un'espressione regolare multilinea, senza distinzione tra maiuscole e minuscole.

Il predicato applicato al valore selezionato copre uguale e diverso, minore e maggiore sia in forma stretta sia inclusiva, appartenenza a un elenco di valori accettabili o esclusione da esso, dentro o fuori un intervallo numerico, e un test sul fatto che il valore sia null o del tutto assente.

Ogni guasto in questa tabella restituisce HTTP 200. È l'intero problema del monitorare un'API basandosi solo sul codice di stato: il trasporto è riuscito, quindi il trasporto segnala successo.

Quell'ultima riga vale la pena farla deliberatamente. Un secondo monitor che non invia credenziali e verifica un 401 è il modo più economico per scoprire che un livello di autorizzazione è stato disattivato per errore - un guasto che nessuna quantità di test positivi farà mai emergere.

I monitor API vengono eseguiti dalla rete pubblica di postazioni di HostTracker - oltre 300 postazioni in 158 città - e tu scegli quali località utilizza un dato monitor. La geografia conta di più per un'API che per un sito web: un endpoint dietro una CDN o un load balancer con instradamento geografico può essere sano a Francoforte e in errore a San Paolo, e un controllo da una sola postazione non ha modo di vederlo. Lo stesso vale per il DNS - un record obsoleto o configurato male spesso si propaga in modo irregolare, il che appare come un'interruzione intermittente dall'interno e come un'interruzione regionale dall'esterno.

Eseguire il controllo da molti luoghi comporta un rischio evidente: più postazioni, più occasioni per un singolo percorso di rete instabile di gridare al lupo. HostTracker gestisce questo con un quorum di conferma. Quando una postazione segnala un fallimento, il controllo viene ripetuto su ulteriori postazioni indipendenti e il cambio di stato viene confermato solo quando concordano - per impostazione predefinita un verdetto a maggioranza su un massimo di sette agenti, con un minimo di tre. Puoi renderlo più rigoroso, richiedendo che un numero fissato di agenti segnali il fallimento o il pieno accordo tra loro, per un endpoint dove un falso avviso è peggio di uno lento.

Dopo la conferma, l'invio degli avvisi segue il ritardo scelto da ciascun contatto - immediatamente, oppure dopo 3, 5, 15, 30 o 60 minuti, o 3, 6, 12 o 24 ore di guasto continuo - sui nove canali di notifica: email, SMS, chiamata vocale, webhook, Slack, e le app di messaggistica Telegram, Discord, Viber, Facebook Messenger e Google Chat. Il canale webhook è il modo in cui gli avvisi raggiungono uno strumento di gestione degli incidenti o di chat di team.

Il controllo è una richiesta HTTP configurabile più l'analisi della risposta, quindi ciò a cui si adatta segue direttamente da questo.

• Le API REST e JSON sono il caso quotidiano, e il monitoraggio delle API REST è ciò che la maggior parte degli account configura per prima: un GET o un POST, intestazioni per la credenziale, e regole JSONPath o di verifica sul payload.
• GraphQL funziona come un POST con la query nel corpo, poi JSONPath dentro data - e vale la pena verificare che il membro errors sia assente, dato che GraphQL è notoriamente capace di rispondere 200 con errori all'interno.
• I servizi SOAP e XML sono un POST con l'envelope come corpo e XPath come selettore, che raggiunge la risposta esattamente nel modo previsto dalla specifica.
• I ricevitori di webhook e gli endpoint di callback possono essere controllati per la raggiungibilità e per la risposta che danno a una richiesta ben formata - prezioso, perché un ricevitore che ha silenziosamente smesso di accettare consegne non produce alcun errore da nessuna parte nel tuo sistema.
• Gli endpoint di health e readiness sono l'obiettivo di maggior valore in assoluto se li hai: la tua applicazione sa già se le sue dipendenze sono sane, e una verifica su quel verdetto trasforma la sua stessa conoscenza in un avviso.

Ciò che non si adatta è una sequenza - ottenere un token, usarlo, poi eliminare la risorsa. Un monitor API effettua una richiesta per esecuzione. Per un percorso genuinamente multi-fase, lo strumento giusto è il controllo transazionale guidato da browser; per i tempi di una pagina invece che di un endpoint, vedi tempistiche di accesso e caricamento pagina da browser.

1. Prova prima l'endpoint con il controllo HTTP istantaneo gratuito - senza bisogno di accesso - così puoi vedere lo stato, i tempi e la risposta contro cui stai per scrivere le regole.
2. Aggiungi un monitor e scegli il tipo di monitoraggio API. Imposta il metodo, e aggiungi le intestazioni o il corpo di cui l'endpoint ha bisogno; emetti per il monitor una credenziale propria invece di riutilizzare quella di una persona.
3. Scrivi le verifiche. Inizia dal pacchetto di quattro righe visto sopra - stato, content type, un valore significativo dal payload, e un budget di tempo di risposta - che è un valore predefinito davvero valido per quasi qualsiasi API JSON.
4. Scegli un intervallo tra un minuto e 24 ore. Tre minuti è il valore predefinito ed è un buon punto di partenza; riserva un minuto agli endpoint la cui interruzione costituisce un incidente.
5. Scegli le postazioni. Due o tre regioni in cui vivono davvero i tuoi consumatori battono una sola, ed è ciò che rende visibile un guasto regionale.
6. Aggiungi i contatti, e imposta il ritardo di avviso di ciascuno. Non tutti hanno bisogno di saperlo al primo minuto.
7. Lascialo girare per un giorno, poi osserva la cronologia dei tempi di risposta prima di stringere la regola sui tempi. Un budget impostato su dati reali regge; uno impostato su una supposizione finisce silenziato.

Sono complementari e spesso confusi tra loro. Una piattaforma di osservabilità o APM strumenta il tuo codice e ti dice cosa è successo dentro una richiesta. Il monitoraggio API esterno sta fuori dalla tua infrastruttura e ti dice cosa riceve davvero un consumatore. Vale la pena avere entrambi; nessuno dei due sostituisce l'altro.

Lo schema su cui si stabilizzano la maggior parte dei team è monitoraggio esterno per il rilevamento e telemetria interna per la diagnosi: HostTracker ti dice che un endpoint si è rotto, da dove e contro quale regola, e il tuo tracing ti dice perché. Accanto a esso, un monitor delle query al database spesso spiega un'API diventata lenta, e il monitoraggio del carico server spiega la macchina su cui gira.

• Una richiesta per esecuzione. Nessuno scambio di token, nessuna chiamata concatenata. Punta il monitor verso un endpoint la cui autenticazione non scade, e usa un controllo transazionale quando ciò che devi dimostrare è una sequenza.
• Venti regole di verifica per monitor. Ampiamente sufficiente nella pratica - il pacchetto di quattro righe copre la maggior parte degli endpoint - ma vale la pena saperlo prima di pianificare un test di contratto da cento regole.
• La modalità di verifica sostituisce le impostazioni più vecchie di parola chiave e stato. I due modelli non possono essere combinati su un monitor; scegli il linguaggio delle regole oppure la modalità a parola chiave legacy, non entrambi.
• Nessuna validazione OpenAPI o JSON-schema. Verifichi valori e strutture specifiche, non un intero documento di schema.
• Il corpo della richiesta ha un limite di lunghezza, quindi un payload POST molto grande non è la forma per cui è pensato questo controllo.
• È monitoraggio, non testing. Il target giusto è un endpoint di sola lettura o idempotente. Un monitor che modifica dati ogni tre minuti da più postazioni finirà prima o poi per essere la causa di un incidente invece che ciò che lo rileva.