Tracking API Güvenilirlik Rehberi: Canlıya Geçiş Sonrasında Çalışma Süresi, Veri Güncelliği ve Kaçırılan Güncellemeler Nasıl İzlenir

Canlıya geçişten sonra, takip API'sinin güvenilirliğini üç ayrı katmanda izleyin: isteklerin başarılı olup olmadığı, gönderi bilgilerinin kabul edilebilir bir gecikme içinde ulaşıp ulaşmadığı ve güncellemelerin boşluklar olmadan kendi sistemlerinize ulaşıp ulaşmadığı. Başarılı bir API yanıtı, takip verilerinin güncel olduğunu veya müşteri bildiriminin teslim edildiğini kanıtlamaz. Her katmana kendi metriklerini, uyarılarını ve kurtarma prosedürünü tanımlayın.

Bu kılavuz, canlı bir gönderi takip entegrasyonundan sorumlu mühendisler ve operasyon ekipleri içindir. Amaç, görünürlükteki bozulmayı bir destek sorununa dönüşmeden tespit etmek ve ardından arızanın taşıyıcı akışında mı, takip sağlayıcısında mı, webhook alıcınızda mı yoksa sonraki işlemlerde mi olduğunu belirlemektir.

Güvenilir bir takip güncellemesinin ne anlama geldiğini tanımlayın

Teslimat yolunun tamamıyla başlayın: gönderi kaydı, sağlayıcıdan veri alma, API yanıtı veya webhook teslimi, dahili işleme, veritabanında kalıcılaştırma ve müşteriye gösterim. Bildirim gönderiyorsanız, kaydedilmiş bir güncellemenin alıcıya ulaştığını varsaymak yerine bunu başka bir aşama olarak ele alın.

Her aşama için sorumlusunu ve başarının kanıtını kaydedin. Bir sağlayıcının takip numarasını kabul etmesi, kaydın kabul edildiğini kanıtlar; taşıyıcının bir olay yayınladığını değil. Bir webhook'un başarılı bir HTTP yanıtı alması, uç noktanızın bunu onayladığını kanıtlar; çalışanınızın güncellemeyi kalıcı olarak kaydettiğini kesin olarak göstermez.

Google'ın SRE kılavuzu gecikme, trafik, hatalar ve doygunluğu izlemenin dört altın sinyali olarak tanımlar. Bu sinyaller entegrasyon altyapınız için yararlıdır; ancak görünüşte sağlıklı bir uç nokta değişmemiş veya eksik bilgi sunabileceğinden gönderi takibi ayrıca güncellik ve eksiksizlik kontrolleri gerektirir.

Uyarıları ayarlamadan önce entegrasyonu ölçümlenebilir hale getirin

Bir gönderiyi kayıt denemesi, gelen güncellemeler, işleme denemeleri ve ortaya çıkan durumla ilişkilendiren operasyonel bir kayıt tutun. Korelasyon için dahili bir gönderi tanımlayıcısı kullanın; mümkün olduğunda takip numaralarını ve müşteri ayrıntılarını geniş erişimli günlüklerden uzak tutun.

Asgari yararlı kayıt şunları içerir:

• Dahili gönderi kimliği, biliniyorsa taşıyıcı tanımlayıcısı, entegrasyon hesabı ve ortam.
• İstek veya korelasyon kimliği, işlem türü, deneme zamanı, sonuç kategorisi ve süre.
• Sağlandığında sağlayıcı olay kimliği ile birlikte özgün olay zaman damgası ve saat dilimi bilgisi.
• Webhook alınma zamanı, kalıcı depolama zamanı, işlemin tamamlanma zamanı ve ölçülebiliyorsa görüntülenebilirlik zamanı.
• Varsa yük şeması sürümü, ayrıştırma sonucu, tekilleştirme sonucu ve hata nedeni.

İnceleme veya yeniden oynatma için gerektiğinde özgün yükü uygun erişim ve saklama kontrolleri altında koruyun. Yetkilendirme başlıklarını veya gizli bilgileri günlüğe kaydetmeyin. Metrikler için taşıyıcı ve sonuç kategorisi gibi sınırlı boyutlar kullanın; tek tek takip numaraları yüksek kardinaliteli metrik etiketlerinde değil, aranabilir kayıtlarda bulunmalıdır.

Olay zamanını gözlem zamanından ayrı tutun. OpenTelemetry günlük veri modeli bu ayrımı Timestamp ve ObservedTimestamp aracılığıyla açıkça yapar. Aynı ayrımı takip kayıtlarına uygulamak, geç bildirilen bir taşıyıcı olayının yavaş bir veritabanı yazma işlemi sanılmasını önlemeye yardımcı olur.

Çalışma süresini uygulamanızın bakış açısından izleyin

Hem gerçek üretim trafiğini hem de düşük hacimli bir sentetik kontrolü kullanın. Üretim trafiği gerçek müşteri etkisini ortaya çıkarır. Sentetik kontrol, belgelenmiş ve yıkıcı olmayan bir işlem kullandığı ve sağlayıcının kullanım sınırlarına uyduğu sürece üretim trafiği sakin olduğunda arızaları tespit edebilir.

Yararlı bir istek-başarı göstergesi şöyledir:

Başarılı uygun işlemler / Tüm uygun denenmiş işlemler

“Başarılı”yı hem HTTP durumunu hem de belgelenmiş uygulama düzeyindeki sonucu kullanarak tanımlayın. Bazı arayüzler başarılı bir HTTP yanıtı döndürürken gövdede başarısız bir işlem bildirebilir. Toplu işlemlerde istek düzeyindeki sonuçların yanı sıra öğe düzeyindeki sonuçları da ölçün.

Hatalar için iki görünüm tutun. Müşteri etkisi görünümü, uygulamanızın görevini tamamlamasını engelleyen her şeyi içerir. Tanılama görünümü sağlayıcı hatalarını, ağ arızalarını, kimlik doğrulama sorunlarını, geçersiz girdileri ve kota ya da hız sınırı yanıtlarını birbirinden ayırır. Süresi dolmuş bir kimlik bilgisi sağlayıcı kesintisi olmayabilir; ancak entegrasyonunuz için yine de bir kesintidir.

• Gecikme: Trafik hacmi anlamlı yüzdelik dilimleri destekliyorsa p50, p95 ve p99'u izleyin. Hızlı hataların gecikmeyi sağlıklı göstermemesi için zaman aşımlarını ayrı ölçün.
• Trafik: İstek ve geri çağrı hacmini gönderi kayıtları ve etkin gönderi popülasyonuyla karşılaştırın.
• Hatalar: Aktarım hatalarını, uygulama hatalarını, ayrıştırma hatalarını ve sonraki kalıcılaştırma hatalarını ayırın.
• Doygunluk: Bağlantı havuzlarını, çalışan kapasitesini, kuyruk derinliğini, kuyruktaki en eski öğeyi ve kullanılabilir istek bütçesini izleyin.

Bu ölçümleri, sözleşmenin kesin tanımlarını kullanmadıkları sürece sağlayıcının sözleşmeye dayalı çalışma süresi olarak sunmayın. Gözlemlenen entegrasyon kullanılabilirliğiniz ile bir tedarikçinin hizmet seviyesi anlaşması farklı soruları yanıtlar.

Sessizliği hatayla karıştırmadan güncelliği ölçün

Hareket etmemiş bir gönderi otomatik olarak güncelliğini yitirmiş değildir. Uluslararası taşıma, aktarmalar, hafta sonları ve taşıyıcıların tarama uygulamaları meşru boşluklar oluşturabilir. İzleme sorunu, “yeni hiçbir şey olmadı” ile “yeni bilgi var ancak sistemimiz bunu almadı” durumlarını birbirinden ayırmaktır.

Ayrı gecikmeler için ayrı saatler kullanın

• Son olay yaşı: Geçerli zaman eksi en son taşıyıcı olayının zamanı. Bu, entegrasyon performansını zorunlu olarak değil, gönderi görünürlüğünü açıklar.
• Alınma gecikmesi: Alınma zamanınız eksi olay zamanı. Ara zaman damgaları yoksa bu, üst akış bildirim ve veri alma gecikmelerini içerir.
• Dahili işleme gecikmesi: Kalıcı işleme tamamlanma zamanı eksi alınma zamanı. Bu, sisteminiz içindeki çalışmayı izole eder.
• Görüntüleme gecikmesi: Müşteriye sunulma zamanı eksi işleme tamamlanma zamanı. Bu, önbellek veya okuma modeli sorunlarını ortaya çıkarabilir.
• Doğrulama yaşı: Geçerli zaman eksi daha yeni bilgi için yapılan son başarılı kontrol. Bu, kontrol etkinliğini ölçer; taşıyıcı akışının güncel olduğunun kanıtı değildir.

Gerekli sağlayıcı zaman damgası mevcutsa ve anlamı belgelenmişse sağlayıcıya özgü veri alma gecikmesini hesaplayın. Bu olmadan alınma gecikmesi adil biçimde tek bir tarafa atfedilemez.

Zaman damgalarını özgün gösterimlerini koruyarak tutarlı bir saat dilimine normalleştirin. Eksik saat dilimi bilgilerini, geleceğe tarihli olayları ve saat tutarsızlıklarını işaretleyin. Negatif gecikmeyi sessizce sıfıra çevirmeyin; inceleyin veya zaman damgası kalitesi sorunu olarak sınıflandırın.

Benzer gönderileri karşılaştırın

Güncellik görünümlerini biliniyorsa taşıyıcıya, hizmete veya rotaya, gönderi durumuna ve kayıttan bu yana geçen zamana göre oluşturun. İlk olayını bekleyen yeni kaydedilmiş gönderileri hâlihazırda taşınmakta olan gönderilerden ayırın. Operasyonel kurallarınıza göre teslim edilmiş gönderileri etkin hareket kontrollerinden çıkarın; ancak iş akışınızın gerektirdiği teslimat sonrası izlemeyi koruyun.

İlk eşikleri uydurma evrensel bir yenileme aralığına değil, iş gereksinimlerine ve gözlemlenen davranışa göre belirleyin. Yerel teslimat için uygun bir eşik, sınır ötesi bir aktarmada gürültü oluşturabilir. Buna karşılık geniş bir ağ ortalaması, tek bir taşıyıcıyı etkileyen sorunu gizleyebilir.

Her güncellik panelini kapsamıyla etiketleyin. Olay zaman damgaları popülasyonun bir bölümünde eksikse, kalan gönderilerin tüm trafiği temsil ediyor gibi görünmesini önlemek için bu popülasyonu ayrı gösterin.

Mutabakat yoluyla kaçırılan güncellemeleri bulun

Tek başına webhook hacmi eksiksizliği kanıtlayamaz. Trafiğin sakin olması normal olabilir ve başarılı bir webhook yanıtı sonraki işleme hatasını gizleyebilir. Mutabakat, bir referans kaynağın şu anda sunduklarını sisteminizin gerçekten kaydettiği veya işlediği verilerle karşılaştırır.

1. Uygun popülasyonu tanımlayın. Kaydedilmiş ve etkin olarak izlenen gönderileri dahil edin. Reddedilen kayıtları ve duraklatılmış izlemeyi operasyonel raporlamada kaybolmamaları için ayrı izleyin.
2. Bir referans seçin. Belgelenmiş API izin veriyorsa güncel takip ayrıntılarını webhook alımından bağımsız olarak alın. Taşıyıcı takip sayfaları tekil vakaları araştırmaya yardımcı olabilir; ancak yetkilendirme olmadan otomatik kazıma bağımlılığına dönüştürülmemelidir.
3. Bir tolerans süresi uygulayın. Bir farkı şüpheli boşluk olarak sınıflandırmadan önce normal teslimat ve işleme gecikmelerine izin verin.
4. Benzeri benzeriyle karşılaştırın. Desteklenen olay tanımlayıcılarını eşleştirin veya zaman damgaları, durumlar, konumlar ve açıklamalar için belgelenmiş bir normalleştirme kuralı kullanın.
5. Güvenli şekilde kurtarın. Saklanan mesajları yeniden oynatın veya izin verilen güncellemeleri normal, idempotent işleme yolu üzerinden alın.
6. Hedefi doğrulayın. Yalnızca kurtarma işinin çalıştığını değil, veritabanının ve müşteriye gösterilen görünümün düzeltildiğini doğrulayın.

Dahili bir gösterge şu şekilde ifade edilebilir:

Çözümlenmemiş farkları bulunan uygun mutabakatlı gönderiler / Tüm uygun mutabakatlı gönderiler

Buna evrensel kaçırılmış olay oranı değil, çözümlenmemiş mutabakat boşluğu oranı deyin. Referans yalnızca son durumu sunuyorsa her geçmiş olayın ulaştığını kanıtlayamaz. Eşleşen bir nihai durum bile ara aşamalardan birinin kaçırıldığını gizleyebilir.

Taşıyıcılar, gönderi yaşları ve durumlar arasında katmanlı bir örneklemle başlayın. Belgelenmiş sınırlara tabi olarak olay sırasında etkilenen segmentler için kapsamı genişletin. Küçük bir örneklemin tam kapsam sanılmaması için hem kontrol edilen sayıyı hem de fark bulunan sayıyı raporlayın.

Webhook alımını kurtarılabilir hale getirin

Alıcıyı gelen istekleri doğrulayacak ve sağlayıcının belgelenmiş teslimat sözleşmesine uygun olarak onay vermeden önce kabul edilen mesajları kalıcı biçimde yakalayacak şekilde tasarlayın. Daha yavaş iş mantığını mümkün olduğunda ayrı bir çalışanda tutun.

Varsaymak yerine gerçek entegrasyon kurallarını doğrulayın: kimlik doğrulama veya imza doğrulaması, onay gereksinimleri, istek zaman aşımı, yeniden deneme koşulları, yeniden deneme süresi, sıralama ve yeniden oynatma kullanılabilirliği. Bu ayrıntılar uygulamanızın hangi kurtarma işlemlerini sağlaması gerektiğini belirler.

• Tasarımınızda yinelenenleri bekleyin: Varsa belgelenmiş bir olay kimliği kullanın. Yoksa kapsamı dikkatle belirlenmiş bir tekilleştirme anahtarı oluşturun ve bunu meşru benzer olaylara karşı test edin.
• Sıra dışı teslimatı yönetin: Olay geçmişini koruyun ve gönderi durumunu alınan son mesajla körü körüne değiştirmek yerine açık geçiş kuralları kullanın.
• Hataları karantinaya alın: İşlenemeyen mesajları hata ayrıntılarıyla saklayın ve kontrollü bir yeniden kuyruğa alma süreci sağlayın.
• Durum kurtarmayı yan etkilerden ayırın: Bir olayın yeniden oynatılması, eski bir teslimat e-postasını veya başka bir müşteriye yönelik işlemi otomatik olarak yeniden göndermemelidir.

Entegrasyonunuz 17TRACK kullanıyorsa uygulama referansı olarak resmi Tracking API documentation belgesini kullanın ve entegrasyonunuz için geçerli gereksinimleri kontrol edin. Tracking API product page ürün bağlamı sağlar; ancak izleme eşikleri ve kurtarma varsayımları ürün açıklamalarından değil, belgelenmiş davranıştan, hizmet sözleşmenizden ve üretim ölçümlerinden alınmalıdır.

Panoları uygulanabilir uyarılara dönüştürün

Her uyarı etkilenen popülasyonu, olası hata aşamasını, iş etkisini ve ilk inceleme adımını tanımlamalıdır. Genel bir “takip güncel değil” uyarısı harekete geçmek için nadiren yeterli bilgi sağlar.

Gürültüyü azaltmak için devam eden ihlaller ve minimum örneklem boyutları kullanın. Kullanılabilirlik ve işleme hedefleri için hata bütçesi, kısa süreli bir anormalliği izin verilen hataların kabul edilemez bir bölümünü tüketen arızadan ayırmaya yardımcı olabilir. Taşıyıcı veri güncelliği hedeflerini mühendislik ekibinizin doğrudan kontrol ettiği hedeflerden ayrı tutun.

Tamamlandığını kanıtlayan bir kurtarma çalışma kılavuzu kullanın

Bir olay başladığında bilinen son sağlıklı noktayı belirleyin ve ilgili kayıtları koruyun. Yeni kayıtların, gelen mesajların, işlemenin veya görüntüleme güncellemelerinin etkilenip etkilenmediğini belirleyin. Ardından yalnızca istek sayılarını raporlamak yerine risk altındaki gönderi popülasyonunu tahmin edin.

Arızalı aşamayı geri yükleyin, belgelenmiş sınırlar içinde yeniden oynatın veya veriyi yeniden alın ve etkilenen popülasyonla mutabakat çalıştırın. Birikmiş iş yaşı normale döndükten, çözümlenmemiş boşluklar hesaba katıldıktan ve müşteriye gösterilen durum kontrol edildikten sonra olayı kapatın. Kurtarılamayan geçmiş güncellemeleri ayrıca kaydedin.

Bu süreci kontrollü arızalarla test edin: kullanılamayan alıcı, hatalı biçimlendirilmiş yük, çalışan kesintisi, yinelenen olay, sıra dışı olay ve süresi dolmuş kimlik bilgisi. Bir test; ekip sorunu tespit ettiğinde, sorumlusunu belirlediğinde, verileri kurtardığında ve yinelenen yan etkilerden kaçındığında başarılıdır; yalnızca uç nokta yeniden erişilebilir olduğunda değil.

SSS

Bir API, takip bilgileri güncelliğini yitirmişken başarılı yanıtlar döndürebilir mi?

Evet. İstek başarısı, bir işlemin arayüz kuralları çerçevesinde tamamlandığını gösterir. Taşıyıcının yeni bir tarama yayınladığını veya sonraki tüm sistemlerin sonucu işlediğini göstermez. Güncelliği ve uçtan uca işlemeyi ayrı izleyin.

Gönderilerde ne sıklıkla mutabakat yapmalıyız?

Aralığı kabul edilebilir tespit gecikmesine, etkin gönderi hacmine, istek bütçesine ve belgelenmiş sınırlara göre seçin. Operasyonel açıdan hassas segmentlerde daha sık kontroller, kapsam için daha geniş zamanlanmış bir tarama kullanın. Her taşıyıcı ve iş akışı için uygun tek bir aralık yoktur.

Webhook etkinliğinin olmaması entegrasyonun bozuk olduğu anlamına mı gelir?

Hayır. Yeni olay olmayabilir. Destekleniyorsa geri çağrı etkinliğini etkin gönderi popülasyonu, son örüntüler, alıcı sağlığı ve bağımsız bir veri alma kontrolüyle karşılaştırın. Yalnızca sessizliğe değil, destekleyici kanıtlara dayanarak uyarı verin.

Yedek olarak sürekli yoklama yapmalı mıyız?

Varsayılan olarak hayır. Kontrolsüz yoklama, görünürlüğü artırmadan istek kapasitesini tüketebilir. Belgelenmiş sınırlar içinde sınırlı mutabakat ve olaya özel veri alma kullanın. Yoklama ile webhook teslimatının sağlayıcınızda nasıl etkileştiğini doğrulayın.

Şüpheli bir sağlayıcı sorununu üst makama bildirirken ne göndermeliyiz?

Etkilenen işlem türlerini, UTC zaman aralıklarını, temizlenmiş istek kimliklerini, yanıt kodlarını, onaylı güvenli bir kanal üzerinden temsili gönderi referanslarını ve beklenen davranışla gözlemlenen davranışı ekleyin. Dahili hangi aşamaları kontrol ettiğinizi açıklayın. Kimlik bilgilerini veya gereksiz müşteri verilerini dahil etmeyin.

Kaynaklar

• Google SRE: Monitoring Distributed Systems — dört altın sinyal ve izleme ilkeleri.
• OpenTelemetry: Logs Data Model — olay zaman damgaları ile gözlemlenen zaman damgaları arasındaki ayrım.
• 17TRACK Tracking API documentation — 17TRACK entegrasyonu için uygulama referansı.
• 17TRACK Tracking API — resmi ürün bağlamı.