Tracking API etibarlılığına dair bələdçi: Go-Live-dan sonra işləkliyi, məlumatların yeniliyini və buraxılmış yeniləmələri necə izləmək olar

İstifadəyə verildikdən sonra izləmə API-sinin etibarlılığını üç ayrı səviyyədə monitorinq edin: sorğuların uğurla icra olunub-olunmaması, göndəriş məlumatlarının qəbul edilə bilən gecikmə ilə gəlib-gəlməməsi və yeniləmələrin boşluqlar olmadan öz sistemlərinizə çatıb-çatmadığı. Uğurlu API cavabı izləmə məlumatlarının aktual olduğunu və ya müştəri bildirişinin çatdırıldığını sübut etmir. Hər bir səviyyə üçün ayrıca metrikalar, xəbərdarlıqlar və bərpa proseduru müəyyən edin.

Bu təlimat canlı göndəriş izləmə inteqrasiyasına cavabdeh olan mühəndislər və əməliyyat komandaları üçündür. Məqsəd görünürlüğün dəstək probleminə çevrilməzdən əvvəl pozulduğunu aşkar etmək, sonra isə nasazlığın daşıyıcı lentində, izləmə provayderində, webhook qəbul edəndə və ya sonrakı emalda yerləşdiyini müəyyən etməkdir.

Etibarlı izləmə yeniləməsinin nə demək olduğunu müəyyən edin

Tam çatdırılma yolundan başlayın: göndərişin qeydiyyatı, provayderdən alınma, API cavabı və ya webhook çatdırılması, daxili emal, verilənlər bazasında saxlanma və müştəriyə göstərilmə. Bildirişlər göndərirsinizsə, saxlanılmış yeniləmənin alıcıya çatdığını fərz etmək əvəzinə bunu ayrıca mərhələ kimi nəzərdən keçirin.

Hər mərhələ üçün məsul şəxsi və uğuru sübut edən dəlili qeyd edin. Provayderin izləmə nömrəsini qəbul etməsi qeydiyyatın qəbul edildiyini sübut edir, daşıyıcının hadisə dərc etdiyini yox. Webhook-un uğurlu HTTP cavabı alması son nöqtənizin onu təsdiqlədiyini sübut edir, lakin işçinizin yeniləməni yaddaşa yazdığını mütləq göstərmir.

Google-un SRE təlimatında gecikmə, trafik, xətalar və doyma monitorinqin dörd qızıl siqnalı kimi təsvir olunur. Bu siqnallar inteqrasiya infrastrukturunuz üçün faydalıdır, lakin göndəriş izləməsi həm də aktuallıq və tamlıq yoxlamaları tələb edir, çünki zahirən sağlam son nöqtə dəyişməmiş və ya natamam məlumat təqdim edə bilər.

Xəbərdarlıqlar təyin etməzdən əvvəl inteqrasiyanı alətlərlə təmin edin

Göndərişi onun qeydiyyat cəhdi, daxil olan yeniləmələri, emal cəhdləri və nəticə vəziyyəti ilə əlaqələndirən əməliyyat qeydi saxlayın. Korrelyasiya üçün daxili göndəriş identifikatorundan istifadə edin; mümkün olduqda izləmə nömrələrini və müştəri məlumatlarını geniş əlçatan loglardan kənarda saxlayın.

Faydalı minimum qeyd aşağıdakıları əhatə edir:

• Daxili göndəriş ID-si, məlum olduqda daşıyıcı identifikatoru, inteqrasiya hesabı və mühit.
• Sorğu və ya korrelyasiya ID-si, əməliyyat növü, cəhd vaxtı, nəticə kateqoriyası və müddət.
• Verildikdə provayder hadisəsinin ID-si, həmçinin ilkin hadisə vaxtı və saat qurşağı məlumatı.
• Webhook-un qəbul vaxtı, davamlı yaddaşda saxlanma vaxtı, emalın tamamlanma vaxtı və ölçülə bildiyi halda göstərilmə vaxtı.
• Mümkün olduqda payload sxeminin versiyası, təhlil nəticəsi, dublikatların aradan qaldırılması nəticəsi və xəta səbəbi.

Araşdırma və ya təkrar oynatma üçün lazım olduqda ilkin payload-u uyğun giriş və saxlama nəzarətləri altında qoruyun. Avtorizasiya başlıqlarını və məxfi məlumatları loglamayın. Metrikalar üçün daşıyıcı və nəticə kateqoriyası kimi məhdud ölçülərdən istifadə edin; ayrı-ayrı izləmə nömrələri yüksək kardinaliteli metrika etiketlərində deyil, axtarıla bilən qeydlərdə saxlanmalıdır.

Hadisə vaxtını müşahidə vaxtından ayrı saxlayın. OpenTelemetry log məlumat modelində bu fərq Timestamp və ObservedTimestamp vasitəsilə açıq şəkildə göstərilir. Eyni fərqin izləmə qeydlərinə tətbiqi gecikmiş daşıyıcı hadisəsinin yavaş verilənlər bazası yazılması kimi səhv başa düşülməsinin qarşısını alır.

İş tətbiqinizin baxışından iş vaxtını monitorinq edin

Həm real istehsal trafikindən, həm də az həcmli sintetik yoxlamadan istifadə edin. İstehsal trafiki faktiki müştəri təsirini göstərir. Sintetik yoxlama istehsal trafiki sakit olduqda nasazlıqları aşkar edə bilər, şərt odur ki, sənədləşdirilmiş, dağıdıcı olmayan əməliyyatdan istifadə etsin və provayderin istifadə limitlərinə riayət etsin.

Faydalı sorğu-uğur göstəricisi:

Successful eligible operations / All eligible attempted operations

“Uğurlu” anlayışını həm HTTP statusu, həm də sənədləşdirilmiş tətbiq səviyyəli nəticə əsasında müəyyən edin. Bəzi interfeyslər uğurlu HTTP cavabı qaytararkən gövdədə uğursuz əməliyyat bildirə bilər. Paket əməliyyatları üçün sorğu səviyyəli nəticələrlə yanaşı element səviyyəli nəticələri də ölçün.

Xətalara iki fərqli baxış saxlayın. Müştəri təsiri baxışı tətbiqinizin tapşırığını tamamlamasına mane olan hər şeyi əhatə edir. Diaqnostik baxış provayder xətalarını, şəbəkə nasazlıqlarını, autentifikasiya problemlərini, etibarsız girişləri və kvota və ya sürət limiti cavablarını ayırır. Müddəti bitmiş etimadnamə provayderin kəsintisi olmaya bilər, lakin inteqrasiyanız üçün yenə də kəsintidir.

• Gecikmə: Trafik həcmi mənalı persentilləri dəstəklədikdə p50, p95 və p99-u izləyin. Vaxt aşmalarını ayrıca ölçün ki, sürətli uğursuzluqlar gecikməni sağlam göstərməsin.
• Trafik: Sorğu və callback həcmini göndəriş qeydiyyatları və aktiv göndəriş kütləsi ilə müqayisə edin.
• Xətalar: Nəqliyyat xətalarını, tətbiq xətalarını, təhlil xətalarını və sonrakı yaddaşda saxlama xətalarını ayırın.
• Doyma: Bağlantı hovuzlarını, işçi tutumunu, növbə dərinliyini, növbədəki ən köhnə elementi və mövcud sorğu büdcəsini monitorinq edin.

Bu ölçmələri provayderin müqavilə üzrə iş vaxtı kimi təqdim etməyin, əgər onlar müqavilədəki dəqiq təriflərdən istifadə etmirsə. Müşahidə etdiyiniz inteqrasiya əlçatanlığı ilə satıcının xidmət səviyyəsi razılaşması fərqli suallara cavab verir.

Sükutu nasazlıqla qarışdırmadan aktuallığı ölçün

Hərəkət etməyən göndəriş avtomatik olaraq köhnəlmiş hesab edilmir. Beynəlxalq daşınma, təhvil-təslimlər, həftəsonları və daşıyıcıların skan təcrübələri qanuni boşluqlar yarada bilər. Monitorinq problemi “yeni heç nə baş verməyib” ilə “yeni məlumat mövcuddur, lakin sistemimiz onu qəbul etməyib” hallarını ayırmaqdır.

Ayrı gecikmələr üçün ayrı saatlardan istifadə edin

• Son hadisənin yaşı: Cari vaxt minus son daşıyıcı hadisəsinin vaxtı. Bu, inteqrasiya fəaliyyətini deyil, göndəriş görünürlüğünü təsvir edir.
• Qəbul gecikməsi: Qəbul vaxtınız minus hadisə vaxtı. Aralıq vaxt göstəriciləri olmadıqda bura yuxarı axın hesabatı və alınma gecikmələri daxildir.
• Daxili emal gecikməsi: Davamlı emalın tamamlanma vaxtı minus qəbul vaxtı. Bu, sisteminiz daxilindəki işi təcrid edir.
• Göstərilmə gecikməsi: Müştəriyə əlçatan olma vaxtı minus emalın tamamlanma vaxtı. Bu, keş və ya oxuma modeli problemlərini üzə çıxara bilər.
• Yoxlama yaşı: Cari vaxt minus daha yeni məlumat üçün son uğurlu yoxlamanın vaxtı. Bu, yoxlama fəaliyyətini ölçür, daşıyıcı lentinin aktual olduğuna sübut deyil.

Lazımi provayder vaxt göstəricisi mövcud olduqda və onun mənası sənədləşdirildikdə provayderə xas qəbul gecikməsini hesablayın. Bu olmadan qəbul gecikməsini ədalətli şəkildə bir tərəfə aid etmək olmaz.

Zaman göstəricilərini ardıcıl saat qurşağına normallaşdırın, lakin onların ilkin təqdimatını qoruyun. Çatışmayan saat qurşağı məlumatlarını, gələcək tarixli hadisələri və saat uyğunsuzluqlarını işarələyin. Mənfi gecikməni səssizcə sıfıra çevirməyin; araşdırın və ya onu vaxt göstəricisinin keyfiyyəti problemi kimi təsnif edin.

Oxşar göndərişləri müqayisə edin

Məlum olduqda daşıyıcı, xidmət və ya marşrut, göndəriş statusu və qeydiyyatdan keçdikdən sonra keçən vaxta görə aktuallıq görünüşləri yaradın. İlk hadisəsini gözləyən yeni qeydiyyatdan keçmiş göndərişləri artıq tranzitdə olan göndərişlərdən ayırın. Əməliyyat qaydalarınıza uyğun olaraq çatdırılmış göndərişləri aktiv hərəkət yoxlamalarından çıxarın, lakin iş prosesinizin tələb etdiyi çatdırılmadan sonrakı monitorinqi saxlayın.

İlkin hədləri uydurulmuş universal yenilənmə intervalına deyil, biznes tələblərinə və müşahidə olunan davranışa əsasən təyin edin. Yerli çatdırılma üçün uyğun hədd sərhədlərarası təhvil-təslim üçün səs-küy yarada bilər. Əksinə, geniş şəbəkə ortalaması bir daşıyıcıya təsir edən problemi gizlədə bilər.

Hər aktuallıq panelini əhatə dairəsi ilə etiketləyin. Əhalinin bir hissəsi üçün hadisə vaxt göstəriciləri yoxdursa, qalan göndərişləri bütün trafiki təmsil edirmiş kimi göstərmək əvəzinə həmin əhalini ayrıca göstərin.

Uzlaşdırma vasitəsilə buraxılmış yeniləmələri tapın

Təkcə webhook həcmi tamlığı müəyyən edə bilməz. Sakit trafik normal ola bilər və uğurlu webhook cavabı sonrakı emal xətasını gizlədə bilər. Uzlaşdırma istinad mənbəyinin hazırda təqdim etdiyi məlumatları sisteminizin faktiki saxladığı və ya emal etdiyi məlumatlarla müqayisə edir.

1. Uyğun əhalini müəyyən edin. Qeydiyyatdan keçmiş və aktiv monitorinq olunan göndərişləri daxil edin. Rədd edilmiş qeydiyyatları və dayandırılmış monitorinqi ayrıca izləyin ki, onlar əməliyyat hesabatlarından yoxa çıxmasın.
2. İstinad seçin. Sənədləşdirilmiş API buna imkan verdikdə, cari izləmə məlumatlarını webhook qəbulundan asılı olmayaraq müstəqil şəkildə əldə edin. Daşıyıcı izləmə səhifələri ayrı-ayrı halların araşdırılmasına kömək edə bilər, lakin icazə olmadan avtomatlaşdırılmış məlumat toplama asılılığına çevrilməməlidir.
3. Güzəşt müddəti tətbiq edin. Fərqi ehtimal olunan boşluq kimi təsnif etməzdən əvvəl normal çatdırılma və emal gecikmələrinə imkan verin.
4. Eyni şeyi eyni ilə müqayisə edin. Dəstəklənən hadisə identifikatorlarını uyğunlaşdırın və ya vaxt göstəriciləri, statuslar, məkanlar və təsvirlər üçün sənədləşdirilmiş normallaşdırma qaydasından istifadə edin.
5. Təhlükəsiz bərpa edin. Saxlanılmış mesajları təkrar oynadın və ya icazə verilən yeniləmələri normal idempotent emal yolu ilə əldə edin.
6. Təyinat yerini təsdiqləyin. Yalnız bərpa işinin işlədiyini deyil, verilənlər bazasının və müştəriyə göstərilən görünüşün düzəldildiyini yoxlayın.

Daxili göstərici belə ifadə edilə bilər:

Eligible reconciled shipments with unresolved differences / All eligible reconciled shipments

Bunu universal buraxılmış hadisə dərəcəsi deyil, həll olunmamış uzlaşdırma boşluğu dərəcəsi adlandırın. İstinad yalnız son vəziyyəti təqdim edirsə, hər tarixi hadisənin çatdığını sübut edə bilməz. Hətta uyğun son status belə aralıq mərhələnin buraxılmasını gizlədə bilər.

Daşıyıcılar, göndəriş yaşları və statuslar üzrə təbəqələndirilmiş nümunə ilə başlayın. Hadisə zamanı sənədləşdirilmiş limitlərə uyğun olaraq təsirə məruz qalan seqmentlər üzrə əhatə dairəsini genişləndirin. Yoxlanılanların sayını və fərqi olanların sayını ayrıca bildirin ki, kiçik nümunə tam əhatə kimi başa düşülməsin.

Webhook qəbulunu bərpa edilə bilən edin

Qəbul edəni daxil olan sorğuları yoxlamaq və təsdiqləməzdən əvvəl qəbul edilmiş mesajları davamlı şəkildə saxlamaq üçün, provayderin sənədləşdirilmiş çatdırılma müqaviləsinə uyğun olaraq dizayn edin. Praktik olduqda daha yavaş biznes məntiqini ayrıca işçidə saxlayın.

İnteqrasiyanın faktiki qaydalarını fərz etmək əvəzinə yoxlayın: autentifikasiya və ya imza yoxlaması, təsdiqləmə tələbləri, sorğu vaxt aşımı, təkrar cəhd şərtləri, təkrar cəhd müddəti, sıralama və təkrar oynatma imkanı. Bu detallar tətbiqinizin hansı bərpanı təmin etməli olduğunu müəyyən edir.

• Dizaynınızda dublikatları gözləyin: Mövcud olduqda sənədləşdirilmiş hadisə ID-sindən istifadə edin. Əks halda diqqətlə məhdudlaşdırılmış dublikatların silinməsi açarı yaradın və onu qanuni oxşar hadisələrə qarşı test edin.
• Sırasız çatdırılmanı idarə edin: Hadisə tarixçəsini qoruyun və göndəriş vəziyyətini son qəbul edilən mesajla kor-koranə əvəz etmək əvəzinə açıq keçid qaydalarından istifadə edin.
• Xətaları təcrid edin: Emal edilə bilməyən mesajları xəta detalları ilə saxlayın və nəzarətli yenidən işə salma prosesi təmin edin.
• Vəziyyətin bərpasını yan təsirlərdən ayırın: Hadisənin təkrar oynadılması köhnə çatdırılma e-poçtunu avtomatik olaraq yenidən göndərməməli və digər müştəriyə yönəlmiş əməliyyatı təkrarlamamalıdır.

İnteqrasiyanız 17TRACK istifadə edirsə, tətbiqetmə istinadı kimi rəsmi Tracking API sənədlərindən istifadə edin və inteqrasiyanıza tətbiq olunan tələbləri yoxlayın. Tracking API məhsul səhifəsi məhsul kontekstini təqdim edir, lakin monitorinq hədləri və bərpa fərziyyələri məhsul təsvirlərindən deyil, sənədləşdirilmiş davranışdan, xidmət müqavilənizdən və istehsal ölçmələrindən irəli gəlməlidir.

Panelləri əməli xəbərdarlıqlara çevirin

Hər xəbərdarlıq təsirə məruz qalan əhalini, ehtimal olunan nasazlıq mərhələsini, biznes təsirini və ilk araşdırma addımını müəyyən etməlidir. Qlobal “izləmə köhnəlib” xəbərdarlığı nadir hallarda tədbir görmək üçün kifayət qədər məlumat verir.

Səs-küyü azaltmaq üçün davamlı pozuntulardan və minimum nümunə ölçülərindən istifadə edin. Əlçatanlıq və emal məqsədləri üçün xəta büdcəsi qısa anomaliyanı icazə verilən xətaların qəbuledilməz hissəsini istehlak edən nasazlıqdan ayırmağa kömək edə bilər. Daşıyıcı məlumatlarının aktuallığı məqsədlərini mühəndislik komandanızın birbaşa nəzarət etdiyi məqsədlərdən ayrı saxlayın.

Tamamlanmanı sübut edən bərpa təlimatından istifadə edin

Hadisə başladıqda son məlum sağlam nöqtəni müəyyən edin və müvafiq qeydləri qoruyun. Yeni qeydiyyatların, daxil olan mesajların, emalın və ya görünüş yeniləmələrinin təsirlənib-təsirlənmədiyini müəyyən edin. Sonra yalnız sorğu saylarını bildirmək əvəzinə risk altında olan göndəriş kütləsini təxmin edin.

Uğursuz mərhələni bərpa edin, sənədləşdirilmiş limitlər daxilində təkrar oynadın və ya yenidən əldə edin, təsirə məruz qalan kütlə üzrə uzlaşdırma aparın. Yalnız backlog yaşı normaya qayıtdıqda, həll olunmamış boşluqlar uçota alındıqda və müştəriyə yönəlmiş vəziyyət yoxlanıldıqda hadisəni bağlayın. Bərpa edilə bilməyən tarixi yeniləmələri ayrıca qeyd edin.

Bu prosesi nəzarətli nasazlıqlarla test edin: əlçatmaz qəbul edən, səhv formatlı payload, işçi kəsintisi, dublikat hadisə, sırasız hadisə və müddəti bitmiş etimadnamə. Komanda problemi aşkar etdikdə, məsulunu müəyyən etdikdə, məlumatı bərpa etdikdə və dublikat yan təsirlərdən qaçdıqda test uğurlu sayılır; son nöqtənin yenidən əlçatan olması təkbaşına kifayət deyil.

FAQ

API izləmə məlumatları köhnə olduğu halda uğurlu cavablar qaytara bilərmi?

Bəli. Sorğunun uğuru əməliyyatın interfeys qaydalarına uyğun tamamlandığını göstərir. Bu, daşıyıcının yeni skan dərc etdiyini və ya bütün sonrakı sistemlərin nəticəni emal etdiyini göstərmir. Aktuallığı və başdan-başa emalı ayrıca monitorinq edin.

Göndərişləri nə qədər tez-tez uzlaşdırmalıyıq?

Tezliyi qəbul edilə bilən aşkarlama gecikməsinə, aktiv göndəriş həcminə, sorğu büdcəsinə və sənədləşdirilmiş limitlərə əsasən seçin. Əməliyyat baxımından həssas seqmentlər üçün daha tez-tez yoxlamalardan, əhatə üçün isə daha geniş planlaşdırılmış yoxlamadan istifadə edin. Hər daşıyıcı və iş prosesi üçün uyğun olan vahid interval yoxdur.

Webhook fəaliyyətinin olmaması inteqrasiyanın pozulduğu deməkdirmi?

Xeyr. Yeni hadisələr olmaya bilər. Callback fəaliyyətini aktiv göndəriş kütləsi, son nümunələr, qəbul edənin sağlamlığı və dəstəkləndikdə müstəqil alınma yoxlaması ilə müqayisə edin. Təkcə sükuta deyil, təsdiqləyici sübutlara əsasən xəbərdarlıq edin.

Ehtiyat kimi fasiləsiz sorğu göndərməliyikmi?

Defolt olaraq yox. Nəzarətsiz sorğular görünürlüğü yaxşılaşdırmadan sorğu tutumunu istehlak edə bilər. Sənədləşdirilmiş limitlər daxilində məhdudlaşdırılmış uzlaşdırma və hadisəyə xas alınmadan istifadə edin. Provayderiniz üçün sorğu göndərmənin və webhook çatdırılmasının necə qarşılıqlı əlaqədə olduğunu təsdiqləyin.

Ehtimal olunan provayder problemini eskalasiya edərkən nə göndərməliyik?

Təsirə məruz qalan əməliyyat növlərini, UTC vaxt aralıqlarını, təmizlənmiş sorğu ID-lərini, cavab kodlarını, təsdiqlənmiş təhlükəsiz kanal vasitəsilə nümayəndəvi göndəriş istinadlarını və gözlənilənlə müşahidə olunan davranışı daxil edin. Hansı daxili mərhələləri yoxladığınızı izah edin. Etimadnamələri və lazımsız müştəri məlumatlarını daxil etməyin.

Mənbələr

• Google SRE: Monitoring Distributed Systems — dörd qızıl siqnal və monitorinq prinsipləri.
• OpenTelemetry: Logs Data Model — hadisə vaxt göstəriciləri ilə müşahidə vaxt göstəriciləri arasındakı fərq.
• 17TRACK Tracking API documentation — 17TRACK inteqrasiyası üçün tətbiqetmə istinadı.
• 17TRACK Tracking API — rəsmi məhsul konteksti.