Nástroj pro monitorování API: dostupnost, doba odezvy a validace z více než 300 lokalit

Monitorování REST API vypadá povrchně jako monitorování dostupnosti, ale je to jiná práce. API nekonzumují lidé, ale kód, a kód je nemilosrdný způsobem, jakým prohlížeč není. Lidský návštěvník toleruje stránku, která se vykreslí trochu špatně; integrace, která dostane pole se špatným typem, se prostě rozbije. Monitorování API proto musí kontrolovat víc vrstev než jen „odpověděl server“, a HostTracker je kontroluje v pořadí, přičemž selže na první, která nedrží.

Vrstvy jedna až tři jsou to, co vám dá běžná kontrola dostupnosti. Čtvrtá a pátá jsou to, co z ní dělá monitorování API - a jsou to právě vrstvy, kde se odehrává většina skutečných incidentů s API.

Než lze cokoli validovat, musí monitor odeslat požadavek, jaký vaše API očekává. Na monitoru API je k dispozici kompletní povrch požadavku:

Nejvýraznějším způsobem, jak odpověď validovat, je napsat pro ni pravidla. Každé pravidlo je jeden řádek, pravidla se kombinují spojkou AND a jeden monitor jich může nést až dvacet. Toto je ověřený startovní balíček pro JSON API:

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

Čtyři řádky, a dohromady pokrývají čtyři vrstvy, na kterých záleží: endpoint odpověděl kódem 2xx, odpověděl JSON, ne chybovou stránkou, tělo obsahuje skutečný výsledek, ne prázdný, a stihlo se to celé v rámci rozpočtu. Mezi jednotlivě užitečná pravidla ze stejného katalogu patří body.json.path("$.status") eq "ok" pro vlastní verdikt zdraví API, body.json.path("$.error") absent pro chybovou položku objevující se v jinak úspěšné odpovědi, body.json.path("$.version") eq "2.4.1" pro odhalení nechtěného návratu na starší verzi, redirects.count eq 0 pro endpoint, který by měl odpovídat přímo, a cert.days.left gt 14 pro certifikát na stejném spojení.

O čem pravidlo umí mluvit

Pravidla čtou subjekty z odpovědi a porovnávají je. Subjekty pokrývají stavový kód; celkovou dobu odezvy a její složky pro spojení, TLS, DNS, hlavičky a tělo; syrové tělo spolu s jeho velikostí a hashem; strukturované dotazy do těla jako JSON, XML, HTML nebo YAML; jednotlivé hlavičky odpovědi; konečnou i původní URL a jejich části; řetěz přesměrování, hop po hopu; zbývající dny platnosti certifikátu, vydavatele a jména; vyjednaný protokol TLS a šifru; adresy, které vrátil DNS; a Set-Cookie. Porovnání jdou od zjevných - rovná se, menší než, větší než - přes contains, startsWith, endsWith, matches pro regulární výraz, containsAny a containsAll pro množinu, in pro seznam přijatelných hodnot a exists, isNumber a unique.

Existuje i osa detekce změn: pravidlo dokáže porovnat hodnotu z tohoto běhu s hodnotou z předchozího, takže můžete ověřit, že se čítač nikdy nevrací zpět nebo že se hash těla nezměnil - tvar pravidla, který odhalí tichý návrat na starší verzi nebo neautorizovanou změnu obsahu spíš než výpadek.

Vedle jazyka pravidel existuje jednodušší cesta s jedinou hodnotou, která je součástí monitorování API tady už dlouho a často je to vše, co kontrola potřebuje. Řeknete monitoru, jak má tělo parsovat, jak z něj vybrat jednu hodnotu a jaká tato hodnota musí být:

• Parsovat jako JSON, a selektorem je výraz JSONPath.
• Parsovat jako XML, a selektorem je výraz XPath - díky čemuž je jednoduché kontrolovat SOAP a další XML služby.
• Brát to jako prostý text, a selektorem je víceřádkový, na velikosti písmen nezávislý regulární výraz.

Predikát aplikovaný na vybranou hodnotu pokrývá rovná se a nerovná se, menší-než a větší-než v ostré i inkluzivní podobě, členství v seznamu přijatelných hodnot nebo vyloučení z něj, uvnitř číselného rozsahu nebo mimo něj, a test na to, zda je hodnota null nebo úplně chybí.

Každé selhání v této tabulce vrací HTTP 200. To je celý problém s monitorováním API jen podle stavového kódu: přenos proběhl úspěšně, takže přenos hlásí úspěch.

Ten poslední řádek stojí za to udělat úmyslně. Druhý monitor, který neposílá žádné přihlašovací údaje a ověřuje 401, je nejlevnější způsob, jak zjistit, že se autorizační vrstva náhodou vypnula - selhání, které žádné množství pozitivního testování nikdy neodhalí.

Monitory API běží z veřejné flotily kontrolních bodů HostTracker - více než 300 kontrolních bodů ve 158 městech - a vy si vybíráte, které lokality daný monitor používá. Geografie je u API důležitější než u webu: endpoint za CDN nebo geo-směrovaným load balancerem může být zdravý ve Frankfurtu a nefunkční v São Paulu, a kontrola z jediné lokality to nemá jak vidět. Totéž platí pro DNS - zastaralý nebo špatně nastavený záznam se často šíří nerovnoměrně, což zevnitř vypadá jako přerušovaný výpadek a zvenčí jako regionální.

Spouštění z mnoha míst přináší zjevné riziko: víc kontrolních bodů, víc příležitostí, aby jedna nespolehlivá síťová trasa vyvolala planý poplach. HostTracker to řeší potvrzovacím kvórem. Když kontrolní bod nahlásí selhání, kontrola se zopakuje na dalších nezávislých kontrolních bodech a změna stavu se potvrdí, teprve když se na ní shodnou - ve výchozím stavu verdikt většiny z až sedmi agentů, s minimem tří. Můžete to zpřísnit a vyžadovat, aby selhání nahlásil konkrétní počet agentů, nebo aby se shodli úplně všichni, pro endpoint, kde je falešné hlášení horší než pomalá odpověď.

Po potvrzení se upozorňování řídí zpožděním, které si zvolil každý kontakt - okamžitě, nebo po 3, 5, 15, 30 či 60 minutách, nebo po 3, 6, 12 či 24 hodinách nepřetržitého selhávání - napříč devíti notifikačními kanály: e-mail, SMS, hlasový hovor, webhook, Slack, web push a messengery Telegram, Discord a Viber. Webhook je způsob, jakým se upozornění dostane do nástroje pro řešení incidentů nebo týmového chatu.

Kontrola je konfigurovatelný HTTP požadavek plus analýza odpovědi, takže z toho přímo plyne, na co se hodí.

• REST a JSON API jsou běžný případ a REST monitorování API je to, co si většina účtů nastaví jako první: GET nebo POST, hlavičky pro přihlašovací údaj a pravidla JSONPath nebo validační pravidla nad tělem.
• GraphQL funguje jako POST s dotazem v těle a poté JSONPath do data - a stojí za to ověřit, že chybí položka errors, protože GraphQL je proslulý tím, že odpovídá 200 i s chybami uvnitř.
• SOAP a XML služby jsou POST s obálkou jako tělem a XPath jako selektorem, který se do odpovědi dostane přesně tak, jak zamýšlí specifikace.
• Příjemci webhooků a callback endpointy lze kontrolovat na dostupnost a na odpověď, kterou dají na dobře formovaný požadavek - cenné proto, že příjemce, který potichu přestal přijímat doručení, nevytvoří chybu nikde ve vašem vlastním systému.
• Health a readiness endpointy jsou ze všech nejcennějším cílem, pokud je máte: vaše aplikace už sama ví, zda jsou její závislosti zdravé, a pravidlo na tomto verdiktu promění vlastní znalost aplikace v upozornění.

Co se nehodí, je posloupnost - získat token, použít ho a poté smazat prostředek. Monitor API odešle jeden požadavek na běh. Pro skutečnou vícekrokovou cestu je nástrojem prohlížečem řízená kontrola transakce; pro časování stránky místo endpointu viz časování přístupu z prohlížeče a načítání stránek.

Pokryjte REST API několika malými monitory, z nichž každý odpovídá na jednu otázku, místo jednoho monitoru, který se snaží zkontrolovat všechno. Tyto čtyři monitory pokrývají běžné způsoby, jak API selže, i když stále odpovídá, a každý je sestavený z pravidel popsaných výše.

1. Health endpoint. Požadavek GET na endpoint, který vaše aplikace už používá k hlášení vlastního stavu. Přidejte status isOk a pravidlo na jeho verdikt, například body.json.path("$.status") eq "ok", aby i selhávající závislost skrytá za odpovědí 200 vyvolala upozornění.
2. Čtení tak, jak ho provádí klient. Odešlete stejnou metodu, hlavičky a přihlašovací údaj, jaké posílá integrace, a ověřte, že odpověď obsahuje data, například body.json.path("$.count") gt 0, a že dorazí v rámci vámi slíbené doby odezvy, například time lt 2s.
3. Požadavek bez přihlašovacího údaje. Přidejte druhý monitor, který žádný neposílá a očekává odpověď 401. Pokud někdy dostane 200, přestala fungovat kontrola přístupu.
4. Certifikát na hostiteli API. Přidejte cert.days.left gt 14 k prvnímu monitoru, aby končící certifikát způsobil selhání kontroly dva týdny předtím, než začnou selhávat klienti.

Spouštějte je z regionů, kde žijí spotřebitelé vašeho API. Selhání se před odesláním upozornění znovu ověří z dalších kontrolních bodů, takže jedna nespolehlivá síťová trasa nevyvolá poplach v týmu. Jeden monitor může mít až dvacet pravidel.

1. Nejprve endpoint vyzkoušejte pomocí bezplatné okamžité HTTP kontroly - bez přihlášení - abyste viděli stav, časování i odpověď, proti kterým chystáte psát pravidla.
2. Přidejte monitor a vyberte typ monitorování API. Nastavte metodu a přidejte hlavičky nebo tělo, které endpoint potřebuje; vydejte monitoru vlastní přihlašovací údaj místo opakovaného použití osobního.
3. Napište validační pravidla. Začněte čtyřřádkovým balíčkem výše - stav, typ obsahu, jedna smysluplná hodnota z těla a rozpočet na dobu odezvy - což je opravdu dobrý výchozí bod pro téměř jakékoli JSON API.
4. Vyberte interval mezi jednou minutou a 24 hodinami. Tři minuty jsou výchozí a rozumný výchozí bod; jednu minutu si nechte na endpointy, u kterých je výpadek incidentem.
5. Vyberte lokality. Dva nebo tři regiony, kde skutečně žijí vaši spotřebitelé, jsou lepší než jeden jediný, a právě to dělá regionální selhání viditelným.
6. Přidejte kontakty a nastavte každému zpoždění upozornění. Ne každý potřebuje vědět o problému hned první minutu.
7. Nechte to běžet den a teprve pak se podívejte na historii doby odezvy, než zpřísníte pravidlo na čas. Rozpočet nastavený podle skutečných dat vydrží; ten nastavený odhadem se nakonec umlčí.

Tyto dvě věci se doplňují a často se zaměňují. Platforma pro observabilitu nebo APM instrumentuje váš kód a řekne vám, co se stalo uvnitř požadavku. Externí monitorování API stojí mimo vaši infrastrukturu a řekne vám, co skutečně dostane spotřebitel. Obojí se vyplatí mít; ani jedno druhé nenahradí.

Vzorec, ke kterému dospěje většina týmů, je externí monitorování pro detekci a interní telemetrie pro diagnostiku: HostTracker vám řekne, že se endpoint rozbil, odkud a proti kterému pravidlu, a vaše vlastní trasování vám řekne proč. Vedle toho často vysvětlí, proč se API zpomalilo, monitor databázových dotazů, a monitoring zátěže serveru vysvětlí stav hostu, na kterém běží.

• Jeden požadavek na běh. Žádná výměna tokenu, žádné řetězené volání. Namiřte monitor na endpoint, jehož autentizace nevyprší, a pro situace, kdy je potřeba dokázat posloupnost, použijte kontrolu transakce.
• Dvacet validačních pravidel na monitor. V praxi bohatě dost - čtyřřádkový balíček pokryje většinu endpointů - ale stojí za to to vědět, než naplánujete stovkou pravidel psaný kontraktní test.
• Režim validačních pravidel nahrazuje starší nastavení klíčových slov a stavu. Oba modely nelze na jednom monitoru kombinovat; vyberte si jazyk pravidel, nebo starší režim klíčových slov, ne obojí.
• Žádná validace podle OpenAPI ani JSON schématu. Ověřujete konkrétní hodnoty a struktury, ne celý dokument schématu.
• Tělo požadavku má limit délky, takže velmi rozsáhlý payload POST není tvar, pro který je tato kontrola navržená.
• Je to monitorování, ne testování. Správným cílem je endpoint jen pro čtení nebo idempotentní. Monitor, který každé tři minuty z několika lokalit mění data, se nakonec sám stane příčinou incidentu, místo aby ho detekoval.