Tracking API patikimumo vadovas: kaip stebėti veikimo laiką, duomenų aktualumą ir praleistus atnaujinimus po paleidimo

Po paleidimo stebėkite sekimo API patikimumą trimis atskirais lygmenimis: ar užklausos sėkmingos, ar siuntos informacija gaunama per priimtiną laiką ir ar atnaujinimai be spragų pasiekia jūsų sistemas. Sėkmingas API atsakymas neįrodo, kad sekimo duomenys yra aktualūs arba kad klientui skirtas pranešimas buvo pristatytas. Kiekvienam lygmeniui nustatykite atskirą metriką, įspėjimus ir atkūrimo procedūrą.

Šis vadovas skirtas inžinieriams ir operacijų komandoms, atsakingoms už veikiančią siuntų sekimo integraciją. Tikslas – aptikti sutrikusį matomumą prieš jam tampant klientų aptarnavimo problema ir nustatyti, ar gedimas susijęs su vežėjo duomenų srautu, sekimo paslaugų teikėju, jūsų webhook imtuvu ar tolesniu apdorojimu.

Apibrėžkite, ką reiškia patikimas sekimo atnaujinimas

Pradėkite nuo viso pristatymo kelio: siuntos registravimo, teikėjo duomenų gavimo, API atsakymo arba webhook pristatymo, vidinio apdorojimo, išsaugojimo duomenų bazėje ir rodymo klientui. Jei siunčiate pranešimus, laikykite tai atskiru etapu, o ne manykite, kad išsaugotas atnaujinimas pasiekė pirkėją.

Kiekvienam etapui užregistruokite jo savininką ir įrodymus, patvirtinančius sėkmę. Teikėjui priėmus sekimo numerį įrodoma, kad registracija priimta, bet ne tai, kad vežėjas paskelbė įvykį. Webhook gavus sėkmingą HTTP atsakymą įrodoma, kad jūsų galinis taškas jį patvirtino, bet nebūtinai kad jūsų darbuotojas įrašė atnaujinimą.

Google SRE gairėse delsa, srautas, klaidos ir prisotinimas apibūdinami kaip keturi pagrindiniai stebėjimo signalai. Šie signalai naudingi jūsų integracijos infrastruktūrai, tačiau siuntų sekimui taip pat reikia aktualumo ir išsamumo patikrų, nes iš pažiūros sveikas galinis taškas gali pateikti nepasikeitusią arba neišsamią informaciją.

Prieš nustatydami įspėjimus, įdiekite integracijos stebėjimą

Saugokite operacinį įrašą, susiejantį siuntą su jos registravimo bandymu, gaunamais atnaujinimais, apdorojimo bandymais ir galutine būsena. Koreliacijai naudokite vidinį siuntos identifikatorių; jei įmanoma, sekimo numerius ir klientų duomenis laikykite atokiau nuo plačiai pasiekiamų žurnalų.

Mažiausias naudingas įrašas apima:

• Vidinį siuntos ID, žinomą vežėjo identifikatorių, integracijos paskyrą ir aplinką.
• Užklausos arba koreliacijos ID, operacijos tipą, bandymo laiką, rezultato kategoriją ir trukmę.
• Teikėjo įvykio ID, jei jis pateiktas, taip pat pradinę įvykio laiko žymą ir laiko juostos informaciją.
• Webhook gavimo laiką, patvariojo saugojimo laiką, apdorojimo užbaigimo laiką ir rodymo pasiekiamumo laiką, jei jį galima išmatuoti.
• Naudingosios apkrovos schemos versiją, jei ji prieinama, analizavimo rezultatą, dublikatų šalinimo rezultatą ir gedimo priežastį.

Kai tai būtina tyrimui ar pakartotiniam paleidimui, išsaugokite pradinę naudingąją apkrovą taikydami tinkamas prieigos ir saugojimo kontrolės priemones. Neregistruokite autorizavimo antraščių ar paslapčių. Metrikoms naudokite ribotų reikšmių dimensijas, pavyzdžiui, vežėją ir rezultato kategoriją; atskiri sekimo numeriai turi būti paieškai skirtuose įrašuose, o ne didelės kardinalumo reikšmės metrikų etiketėse.

Įvykio laiką laikykite atskirai nuo stebėjimo laiko. OpenTelemetry žurnalų duomenų modelis aiškiai atskiria šias reikšmes per Timestamp ir ObservedTimestamp. Taikant tą patį atskyrimą sekimo įrašams, galima išvengti to, kad vėlai praneštas vežėjo įvykis būtų palaikytas lėtu įrašymu į duomenų bazę.

Stebėkite veikimo laiką iš savo programos perspektyvos

Naudokite tikrą gamybinį srautą ir nedidelės apimties sintetinę patikrą. Gamybinis srautas parodo tikrą poveikį klientams. Sintetinė patikra gali aptikti gedimus, kai gamybinis srautas yra nedidelis, jei naudojama dokumentuota, neardanti operacija ir laikomasi teikėjo naudojimo apribojimų.

Naudingas užklausų sėkmės rodiklis:

Sėkmingos tinkamos operacijos / Visos bandytos tinkamos operacijos

„Sėkmingą“ operaciją apibrėžkite naudodami ir HTTP būseną, ir dokumentuotą taikomosios programos lygmens rezultatą. Kai kurios sąsajos gali grąžinti sėkmingą HTTP atsakymą, nors atsakymo turinyje nurodoma, kad operacija nepavyko. Paketinių operacijų atveju matuokite ne tik užklausos, bet ir atskirų elementų rezultatus.

Turėkite du gedimų vaizdus. Poveikio klientui vaizdas apima viską, kas neleidžia jūsų programai atlikti užduoties. Diagnostiniame vaizde atskirkite teikėjo klaidas, tinklo gedimus, autentifikavimo problemas, netinkamą įvestį ir kvotos arba spartos ribojimo atsakymus. Pasibaigęs kredencialas gali reikšti ne teikėjo sutrikimą, tačiau jūsų integracijai tai vis tiek yra sutrikimas.

• Delsa: Kai srauto apimtis leidžia apskaičiuoti prasmingus procentilius, stebėkite p50, p95 ir p99. Skirtuosius laikus matuokite atskirai, kad greiti gedimai nesudarytų sveikos delsos įspūdžio.
• Srautas: Palyginkite užklausų ir atgalinių iškvietimų apimtį su siuntų registracijomis ir aktyvių siuntų skaičiumi.
• Klaidos: Atskirkite perdavimo gedimus, taikomosios programos gedimus, analizavimo klaidas ir tolesnio išsaugojimo gedimus.
• Prisotinimas: Stebėkite ryšių telkinius, darbuotojų pajėgumą, eilės gylį, seniausią eilėje esantį elementą ir prieinamą užklausų biudžetą.

Neteikite šių matavimų kaip teikėjo sutartinio veikimo laiko, nebent jie naudoja tikslius sutartyje apibrėžtus kriterijus. Jūsų stebimas integracijos pasiekiamumas ir tiekėjo paslaugų lygio susitarimas atsako į skirtingus klausimus.

Matuokite aktualumą nepainiokite tylos su gedimu

Nejudėjusi siunta nebūtinai yra pasenusi. Tarptautinis tranzitas, perdavimai, savaitgaliai ir vežėjų skenavimo praktika gali sukelti teisėtas spragas. Stebėjimo užduotis – atskirti „nieko naujo neįvyko“ nuo „nauja informacija egzistuoja, bet mūsų sistema jos negavo“.

Atskiriems vėlavimams naudokite atskirus laikrodžius

• Naujausio įvykio amžius: Dabartinis laikas minus naujausio vežėjo įvykio laikas. Tai apibūdina siuntos matomumą, bet nebūtinai integracijos veikimą.
• Gavimo delsa: Jūsų gavimo laikas minus įvykio laikas. Kai tarpinių laiko žymų nėra, tai apima ankstesnio srauto pranešimo ir gavimo delsą.
• Vidinio apdorojimo delsa: Patvariojo apdorojimo užbaigimo laikas minus gavimo laikas. Tai atskiria jūsų sistemos viduje atliekamą darbą.
• Rodymo delsa: Pasiekiamumo klientui laikas minus apdorojimo užbaigimo laikas. Tai gali atskleisti podėlio arba skaitymo modelio problemas.
• Patikros amžius: Dabartinis laikas minus paskutinės sėkmingos naujesnės informacijos patikros laikas. Tai matuoja tikrinimo veiklą, o ne įrodo, kad vežėjo duomenų srautas yra aktualus.

Teikėjui būdingą gavimo delsą skaičiuokite tik tada, kai yra reikalinga teikėjo laiko žyma ir jos reikšmė yra dokumentuota. Be jos gavimo delsos negalima teisingai priskirti vienai šaliai.

Normalizuokite laiko žymas į nuoseklią laiko juostą, tačiau išsaugokite jų pradinį atvaizdavimą. Pažymėkite trūkstamą laiko juostos informaciją, ateities datos įvykius ir laikrodžių neatitikimus. Neverskite neigiamos delsos tyliai į nulį; ją ištirkite arba priskirkite laiko žymos kokybės problemai.

Palyginkite panašias siuntas

Kurkite aktualumo vaizdus pagal vežėją, paslaugą arba maršrutą, jei jie žinomi, siuntos būseną ir laiką nuo registracijos. Atskirai vertinkite naujai užregistruotas siuntas, laukiančias pirmojo įvykio, ir jau tranzitu gabenamas siuntas. Pagal savo veiklos taisykles neįtraukite pristatytų siuntų į aktyvaus judėjimo patikras, tačiau išsaugokite bet kokį po pristatymo reikalingą stebėjimą.

Pradinius slenksčius nustatykite remdamiesi verslo reikalavimais ir stebimu elgesiu, o ne sugalvotu universaliu atnaujinimo intervalu. Vietiniam pristatymui tinkamas slenkstis gali sukelti triukšmą tarpvalstybinio perdavimo atveju. Ir atvirkščiai, platus tinklo vidurkis gali paslėpti vieną vežėją paveikusią problemą.

Kiekviename aktualumo skydelyje nurodykite jo aprėptį. Jei daliai siuntų nėra įvykių laiko žymų, rodykite tą dalį atskirai, o ne sudarykite įspūdį, kad likusios siuntos atspindi visą srautą.

Sutikrinimu raskite praleistus atnaujinimus

Vien webhook srauto nepakanka išsamumui nustatyti. Mažas srautas gali būti įprastas, o sėkmingas webhook atsakymas gali paslėpti tolesnio apdorojimo gedimą. Sutikrinant lyginama tai, ką šiuo metu atskleidžia etaloninis šaltinis, su tuo, ką jūsų sistema iš tikrųjų išsaugojo arba apdorojo.

1. Apibrėžkite tinkamą populiaciją. Įtraukite užregistruotas ir aktyviai stebimas siuntas. Atmestas registracijas ir pristabdytą stebėjimą sekite atskirai, kad jie nedingtų iš operacinių ataskaitų.
2. Pasirinkite etaloną. Jei dokumentuota API tai leidžia, dabartinę sekimo informaciją gaukite nepriklausomai nuo webhook gavimo. Vežėjų sekimo puslapiai gali padėti tirti atskirus atvejus, tačiau be leidimo neturėtų tapti automatizuoto nuskaitymo priklausomybe.
3. Taikykite atidėjimo laikotarpį. Prieš klasifikuodami skirtumą kaip įtariamą spragą, suteikite laiko įprastiems pristatymo ir apdorojimo vėlavimams.
4. Lyginkite tapačius dalykus. Sutapdinkite palaikomus įvykių identifikatorius arba naudokite dokumentuotą laiko žymų, būsenų, vietų ir aprašymų normalizavimo taisyklę.
5. Saugiai atkurkite. Iš naujo paleiskite išsaugotus pranešimus arba per įprastą idempotentinį apdorojimo kelią gaukite leidžiamus atnaujinimus.
6. Patvirtinkite paskirties vietą. Patikrinkite, kad duomenų bazė ir klientui skirtas vaizdas būtų ištaisyti, o ne tik tai, kad buvo paleista atkūrimo užduotis.

Vidinį rodiklį galima išreikšti taip:

Tinkamos sutikrintos siuntos su neišspręstais skirtumais / Visos tinkamos sutikrintos siuntos

Vadinkite tai neišspręstų sutikrinimo spragų rodikliu, o ne universaliu praleistų įvykių rodikliu. Jei etalonas pateikia tik naujausią būseną, jis negali įrodyti, kad gautas kiekvienas istorinis įvykis. Net sutampanti galutinė būsena gali paslėpti praleistą tarpinį etapą.

Pradėkite nuo stratifikuotos imties pagal vežėjus, siuntų amžių ir būsenas. Incidento metu išplėskite paveiktų segmentų aprėptį, laikydamiesi dokumentuotų apribojimų. Nurodykite ir patikrintų siuntų skaičių, ir siuntų su skirtumais skaičių, kad maža imtis nebūtų palaikyta visiška aprėptimi.

Padarykite webhook gavimą atkuriamą

Sukurkite imtuvą taip, kad jis tikrintų gaunamas užklausas ir prieš patvirtindamas jas patvariai užfiksuotų priimtus pranešimus, laikydamasis dokumentuotos teikėjo pristatymo sutarties. Jei praktiška, lėtesnę verslo logiką laikykite atskirame darbuotoje.

Patikrinkite tikrąsias integracijos taisykles, o ne darykite prielaidas: autentifikavimą arba parašo tikrinimą, patvirtinimo reikalavimus, užklausos skirtąjį laiką, pakartotinio bandymo sąlygas, pakartotinio bandymo trukmę, eiliškumą ir pakartotinio paleidimo galimybę. Šios detalės lemia, kokį atkūrimą turi užtikrinti jūsų programa.

• Projektuodami numatykite dublikatus: Jei įmanoma, naudokite dokumentuotą įvykio ID. Kitu atveju sukurkite kruopščiai apribotą dublikatų šalinimo raktą ir išbandykite jį su teisėtais panašiais įvykiais.
• Tvarkykite ne eilės tvarka pristatomus įvykius: Išsaugokite įvykių istoriją ir naudokite aiškias būsenų perėjimo taisykles, o ne aklai pakeiskite siuntos būseną paskutine gauta žinute.
• Izoliuokite gedimus: Išsaugokite neapdorojamus pranešimus su jų klaidų informacija ir suteikite kontroliuojamą pakartotinio perdavimo procesą.
• Atskirkite būsenos atkūrimą nuo šalutinių veiksmų: Pakartotinis įvykio paleidimas neturėtų automatiškai išsiųsti seno pristatymo el. laiško ar pakartoti kito klientui skirto veiksmo.

Jei jūsų integracija naudoja 17TRACK, naudokite oficialią Tracking API dokumentaciją kaip įgyvendinimo šaltinį ir patikrinkite jūsų integracijai taikomus reikalavimus. Tracking API produkto puslapyje pateikiamas produkto kontekstas, tačiau stebėjimo slenksčiai ir atkūrimo prielaidos turėtų būti grindžiami dokumentuotu elgesiu, jūsų paslaugų sutartimi ir gamybiniais matavimais, o ne produkto aprašymais.

Paverskite skydelius į veiksmingus įspėjimus

Kiekviename įspėjime turi būti nurodyta paveikta populiacija, tikėtinas gedimo etapas, poveikis verslui ir pirmasis tyrimo veiksmas. Visuotinis įspėjimas „sekimo duomenys pasenę“ retai suteikia pakankamai informacijos veikti.

Triukšmui mažinti naudokite ilgai trunkančius slenksčių viršijimus ir minimalius imties dydžius. Pasiekiamumo ir apdorojimo tikslams klaidų biudžetas gali padėti atskirti trumpą anomaliją nuo gedimo, sunaudojančio nepriimtiną leidžiamų klaidų dalį. Vežėjo duomenų aktualumo tikslus laikykite atskirai nuo tikslų, kuriuos tiesiogiai kontroliuoja jūsų inžinerijos komanda.

Naudokite atkūrimo procedūrą, įrodančią užbaigimą

Prasidėjus incidentui nustatykite paskutinį žinomą sveiką tašką ir išsaugokite svarbius įrašus. Nustatykite, ar paveiktos naujos registracijos, gaunami pranešimai, apdorojimas arba rodymo atnaujinimai. Tada įvertinkite rizikuojančių siuntų populiaciją, o ne praneškite tik užklausų skaičių.

Atkurkite sugedusį etapą, neviršydami dokumentuotų ribų pakartotinai paleiskite arba gaukite duomenis iš naujo ir atlikite paveiktos populiacijos sutikrinimą. Incidentą uždarykite tik tada, kai neatliktų darbų amžius grįžta į normą, atsižvelgta į neišspręstas spragas ir patikrinta klientui rodoma būsena. Atskirai užregistruokite istorinius atnaujinimus, kurių neįmanoma atkurti.

Išbandykite šį procesą kontroliuojamais gedimais: nepasiekiamu imtuvu, netinkama naudinga apkrova, darbuotojo sutrikimu, pasikartojančiu įvykiu, ne eilės tvarka gautu įvykiu ir pasibaigusiu kredencialu. Testas laikomas sėkmingu, kai komanda aptinka problemą, nustato jos savininką, atkuria duomenis ir išvengia pasikartojančių šalutinių veiksmų, o ne vien tada, kai galinis taškas vėl tampa pasiekiamas.

DUK

Ar API gali grąžinti sėkmingus atsakymus, kai sekimo informacija yra pasenusi?

Taip. Užklausos sėkmė patvirtina, kad operacija buvo užbaigta pagal sąsajos taisykles. Ji nepatvirtina, kad vežėjas paskelbė naują skenavimą arba kad kiekviena tolesnė sistema apdorojo rezultatą. Aktualumą ir viso proceso apdorojimą stebėkite atskirai.

Kaip dažnai turėtume sutikrinti siuntas?

Pasirinkite dažnį pagal priimtiną aptikimo delsą, aktyvių siuntų apimtį, užklausų biudžetą ir dokumentuotus limitus. Operaciškai jautriems segmentams naudokite dažnesnes patikras, o aprėpčiai – platesnį suplanuotą patikrinimą. Nėra vieno intervalo, tinkamo kiekvienam vežėjui ir procesui.

Ar webhook veiklos nebuvimas reiškia, kad integracija neveikia?

Ne. Gali nebūti naujų įvykių. Palyginkite atgalinių iškvietimų veiklą su aktyvių siuntų populiacija, naujausiais modeliais, imtuvo būkle ir, jei palaikoma, nepriklausoma gavimo patikra. Įspėkite remdamiesi patvirtinančiais įrodymais, o ne vien tyla.

Ar turėtume nuolat vykdyti apklausą kaip atsarginį mechanizmą?

Ne pagal numatytuosius nustatymus. Nekontroliuojama apklausa gali sunaudoti užklausų pajėgumą nepagerindama matomumo. Naudokite ribotą sutikrinimą ir konkrečiam incidentui skirtą gavimą, laikydamiesi dokumentuotų limitų. Patvirtinkite, kaip jūsų teikėjo atveju sąveikauja apklausa ir webhook pristatymas.

Ką turėtume pateikti eskaluodami įtariamą teikėjo problemą?

Nurodykite paveiktus operacijų tipus, UTC laiko intervalus, nuasmenintus užklausų ID, atsakymų kodus, reprezentatyvias siuntų nuorodas per patvirtintą saugų kanalą ir tikėtiną bei stebėtą elgesį. Paaiškinkite, kuriuos vidinius etapus patikrinote. Neteikite kredencialų ar nereikalingų klientų duomenų.

Šaltiniai

• Google SRE: Monitoring Distributed Systems – keturi pagrindiniai signalai ir stebėjimo principai.
• OpenTelemetry: Logs Data Model – įvykių laiko žymų ir stebėtų laiko žymų skirtumas.
• 17TRACK Tracking API documentation – 17TRACK integracijos įgyvendinimo šaltinis.
• 17TRACK Tracking API – oficialus produkto kontekstas.