Korelasyon ID'leri uçtan uca: frontend'de bir ID oluşturmayı, API'ler boyunca iletmeyi ve loglara eklemeyi gösterir; böylece destek ekipleri sorunları hızlıca izleyebilir.
Destek ekipleri neredeyse hiç temiz bir hata raporu almaz. Bir kullanıcı, "Pay tuşuna tıkladım ve başarısız oldu" der; ama o tek tıklama tarayıcıyı, bir API gateway'ini, ödeme servisini, veritabanını ve bir arka plan işini tetikleyebilir. Her parça kendi hikâyesinin bir dilimini farklı zamanlarda, farklı makinelerde loglar. Ortak bir etiket olmadan hangi log satırlarının birbiriyle ilişkili olduğunu tahmin etmek zorunda kalırsınız.
Korelasyon ID'si işte o ortak etikettir. Bir kullanıcı eylemine (veya mantıksal bir iş akışına) bağlı tek bir ID'dir ve her istek, retry ve servis atlayışı boyunca taşınır. Gerçek uçtan uca kapsama ile kullanıcı şikayetiyle başlayıp sistemler arasında tam zaman çizelgesini çekebilirsiniz.
İnsanlar bazen benzer birkaç ID'yi karıştırır. İşte net ayrım:
İyi uygulama basittir: kullanıcı bir sorun bildirir, siz ondan UI'de gösterilen (veya destek ekranında bulunan) korelasyon ID'sini istersiniz ve ekipten herhangi biri dakikalar içinde tam hikâyeyi bulabilir. Frontend isteğini, API yanıtını, backend adımlarını ve veritabanı sonucunu hepsini birbirine bağlı olarak görürsünüz.
Herhangi bir şey üretmeden önce birkaç kural üzerinde anlaşın. Her ekip farklı bir başlık adı veya log alanı seçerse, destek yine hangi satırların ilişkili olduğunu tahmin etmek zorunda kalır.
Bir kanonik adla başlayın ve her yerde onu kullanın. Yaygın bir seçim X-Correlation-Id gibi bir HTTP başlığı ve correlation_id gibi yapılandırılmış bir log alanıdır. Bir yazım ve bir harf büyük/küçük kullanımı seçin, belgelenmiş olsun ve ters proxy'nizin veya gateway'inizin başlığı yeniden adlandırmayacağından ya da silmediğinden emin olun.
Kopyalanması kolay ve biletlerde/sohbetlerde paylaşılması güvenli bir format seçin. UUID'ler yaygındır çünkü benzersiz ve sade olurlar. ID'yi kopyalayabilecek kadar kısa, ancak çakışma riski yaratmayacak kadar uzun tutun. Tutarlılık zekâsızlıktan iyidir.
Ayrıca ID'nin nerede görünmesi gerektiğine karar verin ki insanlar gerçekten kullanabilsin. Uygulamada bunun isteklerde, loglarda ve hata çıktılarında olması ve ekibinizin kullandığı araçta aranabilir olması gerekir.
Bir ID'nin ne kadar süre hayatta kalacağına karar verin. İyi bir varsayılan, bir kullanıcı eylemi kadardır: örneğin "Pay tuşuna tıklandı" veya "profil kaydedildi". Hizmetler ve kuyruklar arasında uzun akışlar için iş akışı bitene kadar aynı ID'yi koruyun, sonra sonraki eylem için yeni bir tane başlatın. "Tüm oturum için bir ID" uygulamasından kaçının çünkü aramalar hızla gürültülü olur.
Sert bir kural: ID içinde kişisel veri asla bulunmasın. E-posta, telefon, kullanıcı ID'si veya sipariş numarası koymayın. Bu bağlama ihtiyaç varsa, doğru gizlilik kontrolleriyle ayrı alanlarda loglayın.
Korelasyon ID'si oluşturmanın en kolay yeri, kullanıcı ilgilendiğiniz bir eylemi başlattığı andır: "Kaydet"e tıklama, bir form gönderme veya birden fazla isteği tetikleyen bir akış. Backend'e kadar beklerseniz, genellikle hikâyenin ilk kısmını (UI hataları, retry'ler, iptal edilen istekler) kaybedersiniz.
Rastgele, benzersiz bir format kullanın. UUID v4 yaygındır çünkü modern tarayıcılarda oluşturması kolaydır ve çakışma olasılığı düşüktür. ID'yi opak tutun (kullanıcı adları, e-postalar veya zaman damgaları içermesin) ki başlıklar ve loglarda kişisel veri sızmasın.
"İş akışı"nu, birden fazla isteği tetikleyebilen tek bir kullanıcı eylemi olarak ele alın: doğrula, yükle, kayıt oluştur, sonra listeleri yenile. İş akışı başladığında bir ID oluşturun ve akış sonlanana (başarı, hata veya kullanıcı iptali) kadar saklayın. Basit bir desen, onu component state'te veya hafif bir istek bağlamı nesnesinde tutmaktır.
Kullanıcı aynı eylemi iki kez başlatırsa, ikinci deneme için yeni bir korelasyon ID'si üretin. Bu, destek ekibinin "aynı tıklama yeniden denendi" ile "iki ayrı gönderim" arasındaki farkı görmesini sağlar.
ID'yi iş akışı tarafından tetiklenen her API çağrısına ekleyin, genellikle X-Correlation-ID gibi bir başlık üzerinden. Paylaşılan bir API istemcisi (fetch sarmalayıcı, Axios örneği vb.) kullanıyorsanız, ID'yi bir kez verip istemcinin tüm çağrılara eklemesini sağlayın.
// 1) kullanıcı eylemi başladığında
const correlationId = crypto.randomUUID(); // UUID v4 modern tarayıcılarda
// 2) bu iş akışındaki her isteğe geçirin
await api.post('/orders', payload, {
headers: { 'X-Correlation-ID': correlationId }
});
await api.get('/orders/summary', {
headers: { 'X-Correlation-ID': correlationId }
});
UI'niz iş akışıyla alakasız arka plan istekleri (polling, analytics, otomatik yenileme) yapıyorsa, bu istekler için iş akışı ID'sini yeniden kullanmayın. Korelasyon ID'lerini odaklı tutun ki bir ID bir hikâyeyi anlatsın.
Tarayıcıda bir korelasyon ID oluşturduktan sonra iş basittir: frontend her istekle ID'yi göndermeli ve her API sınırında değişmeden varmalıdır. Takımlar yeni uç noktalar, yeni istemciler veya yeni middleware ekledikçe burası en sık kırılan yerdir.
En güvenli varsayılan, her çağrıda HTTP başlığıdır (örneğin X-Correlation-Id). Başlıklar tek bir yerde (fetch sarmalayıcı, Axios interceptor, mobil ağ katmanı) eklenmesi kolaydır ve payload değiştirmeyi gerektirmez.
Eğer çapraz-kaynak (CORS) istekleriniz varsa, API'nizin bu başlığa izin verdiğinden emin olun. Aksi halde tarayıcı başlığı sessizce engelleyebilir ve siz göndermeye çalıştığınızı sanırken göndermemiş olursunuz.
ID'yi sorgu dizesine veya istek gövdesine koymanız gerekiyorsa (bazı üçüncü taraf araçlar veya dosya yüklemeleri bunu dayatır), tutarlı olun ve bunu yazılı hale getirin. Tek bir alan adı seçin ve her yerde onu kullanın. correlationId, requestId ve cid gibi farklı isimleri endpoint'e göre karıştırmayın.
Retry'ler başka bir yaygın tuzaktır. Retry aynı kullanıcı eylemi içinse aynı korelasyon ID'sini korumalıdır. Örnek: kullanıcı "Kaydet"e tıklar, ağ düşer, istemciniz POST'u tekrar dener. Destek tek bir bağlı iz yerine üç alakasız iz görmemeli. Yeni bir kullanıcı tıklaması (veya yeni bir arka plan işi) yeni bir ID almalıdır.
WebSocket'lerde ID'yi yalnızca ilk el sıkışmasında değil, mesaj zarfında da bulundurun. Bir bağlantı birçok kullanıcı eylemi taşıyabilir.
Hızlı bir güvenilirlik kontrolü isterseniz, basit tutun:
correlationId alanı içerir.API kenarınız (gateway, yük dengeleyici veya trafiği alan ilk web servisi), korelasyon ID'lerinin güvenilir olacağı veya tahmine dayalı hale geleceği yerdir. Bu giriş noktasını doğruluk kaynağı olarak ele alın.
Gelen bir ID varsa kabul edin, ama her zaman orada olduğunu varsaymayın. Eksikse hemen yeni bir tane oluşturun ve isteğin geri kalanı için kullanın. Bu, bazı istemciler eski veya hatalı yapılandırılmış olsa bile işin yürümesini sağlar.
Kötü değerlerin loglarınızı kirletmemesi için hafif doğrulama yapın. İzin verici olun: uzunluk ve izin verilen karakterleri kontrol edin, fakat gerçek trafiği reddedecek katı formatlardan kaçının. Örneğin, 16-64 karakter ve harf, sayı, tire ve alt çizgiye izin verin. Eğer değer doğrulamadan geçmezse, yenisiyle değiştirin ve devam edin.
ID'yi çağırana görünür kılın. Her zaman bunu yanıt başlıklarında döndürün ve hata gövdelerine dahil edin. Böylece kullanıcı UI'den kopyalayabilir veya destek ekibi ID'yi isteyip doğru log zincirini bulabilir.
Pratik bir kenar politikası şöyle görünür:
X-Correlation-ID (veya seçtiğiniz başlık) oku.X-Correlation-ID ekle.Örnek hata yükü (destek biletlerinde ve ekran görüntülerinde görünmesi gereken):
{
"error": {
"code": "PAYMENT_FAILED",
"message": "We could not confirm the payment.",
"correlation_id": "c3a8f2d1-9b24-4c61-8c4a-2a7c1b9c2f61"
}
}
İstek backend'e ulaştığında korelasyon ID'sini istek bağlamının bir parçası olarak ele alın; global bir değişkende saklamak yerine akışın her noktasına bağlamı geçirmeniz gerekir. Global değişkenler, aynı anda iki isteği işlediğinizde veya async işler yanıt sonrası devam ettiğinde çöküverir.
Ölçeklenen bir kural: loglayabilen veya başka bir servisi çağırabilen her fonksiyon, ID'yi içeren bağlamı almalı. Go servislerinde bu genellikle context.Context'i handler'lardan iş mantığına ve istemci koduna kadar geçirmek anlamına gelir.
Servis A, Servis B'yi çağırdığında aynı ID'yi giden isteğe kopyalayın. Uçuş ortasında yeni bir tane üretmeyin; eğer üretmeniz gerekirse orijinali ayrı bir alan (parent_correlation_id gibi) olarak saklayın. ID'leri değiştirirseniz, destek hikâyeyi takip edemez.
Aktarım genellikle birkaç tahmin edilebilir yerde kaçırılır: istekte tetiklenen arka plan işleri, istemci kütüphanelerindeki retry'ler, daha sonra tetiklenen webhook'lar ve fan-out çağrılar. Her async mesaj (kuyruk/iş) ID taşımalı ve her retry mantığı bunu korumalıdır.
Loglar correlation_id gibi sabit bir alan adıyla yapılandırılmış olmalı. Her yerde bir yazımı seçin ve ona sadık kalın. requestId, req_id ve traceId karışmasından kaçının; eğer karıştırıyorsanız net bir eşleme tanımlayın.
Mümkünse ID'yi veritabanı görünürlüğüne de dahil edin. Pratik bir yaklaşım, sorgu yorumlarına veya oturum meta verisine eklemektir ki yavaş sorgu logları da bunu göstersin. Biri "Kaydet düğmesi 10 saniye sürdü" dediğinde, destek correlation_id=abc123 ile arayıp API logunu, downstream servis çağrısını ve gecikmeye neden olan yavaş SQL sorgusunu görebilsin.
Korelasyon ID'si, insanlar onu bulup takip edebiliyorsa işe yarar. Bunu logların birinci sınıf alanı yapın (mesaj dizisinin içinde gömülü olmayacak şekilde) ve her servis arasında log kaydının geri kalanını tutarlı tutun.
Korelasyon ID'sini, "ne zaman, nerede, ne oldu ve kim" sorularına cevap veren birkaç alanla eşleştirin (kullanıcı güvenliği gözetilerek). Çoğu ekip için bu şunlardır:
timestamp (zaman dilimi ile)service ve env (api, worker, prod, staging)route (veya operasyon adı) ve methodstatus ve duration_msaccount_id veya tek yönlü hash'lenmiş bir kullanıcı id'si, e-posta değil)Bunlarla destek ID ile arama yapıp doğru isteğe ulaştığını onaylayabilir ve hangi servisin işlediğini görebilir.
Her istek için uzun bir döküm yerine birkaç güçlü iz bırakmayı hedefleyin.
rows=12).Gürültülü loglardan kaçınmak için debug seviyesi ayrıntıları varsayılan kapalı tutun ve yalnızca sorunu bulmaya yardımcı olacak olayları info seviyesine çıkarın. Bir satır problemi yerini bulmaya veya etkisini ölçmeye yardımcı olmuyorsa, muhtemelen info seviyesinde olmamalıdır.
Kırpma (redaction) yapı kadar önemlidir. Korelasyon ID'si veya loglarda PII asla bulunmamalıdır: e-posta, isim, telefon, tam adres veya ham tokenlar gibi. Bir kullanıcıyı tanımlamanız gerekiyorsa dahili ID veya tek yönlü hash kullanın.
Bir kullanıcı destek ekibine mesaj atar: "Ödeme yapmayı denedim, Pay tuşuna tıkladığımda hata oldu." En iyi takip sorusu basittir: "Hata ekranında gösterilen korelasyon ID'sini yapıştırabilir misiniz?" Yanıt olarak cid=9f3c2b1f6a7a4c2f verirler.
Destek şimdi UI, API ve veritabanı çalışmalarını birleştiren bir tutamağa sahip. Hedef, o eylemle ilgili her log satırının aynı ID'yi taşımasıdır.
Destek 9f3c2b1f6a7a4c2f ile loglarda arama yapar ve akışı görür:
frontend INFO cid=9f3c2b1f6a7a4c2f event="checkout_submit" cart=3 items
api INFO cid=9f3c2b1f6a7a4c2f method=POST path=/api/checkout user=1842
api ERROR cid=9f3c2b1f6a7a4c2f msg="payment failed" provider=stripe status=502
Mühendis aynı ID'yi bir sonraki adımda da takip eder. Aranan nokta, backend servis çağrılarının (ve kuyruk işlerinin) ID'yi iletmesidir.
payments INFO cid=9f3c2b1f6a7a4c2f action="charge" amount=49.00 currency=USD
payments ERROR cid=9f3c2b1f6a7a4c2f err="timeout" upstream=stripe timeout_ms=3000
db INFO cid=9f3c2b1f6a7a4c2f query="insert into failed_payments" rows=1
Artık sorun somut: ödeme servisi 3 saniye sonra zaman aşımına uğramış ve bir hata kaydı yazılmış. Mühendis son deploy'ları kontrol edebilir, timeout ayarlarında değişiklik olup olmadığını doğrulayabilir ve retry'lerin olup olmadığını görebilir.
Döngüyü kapatmak için dört kontrol yapın:
Korelasyon ID'lerini işe yaramaz hale getirmenin en hızlı yolu zinciri kırmaktır. Çoğu hata, inşa sırasında zararsız görünen küçük kararlardan kaynaklanır, ancak destek cevap aramaya çalıştığında zarar verir.
Klasik bir hata, her atlayışta taze bir ID üretmektir. Tarayıcı bir ID gönderiyorsa, API gateway'iniz onu tutmalı, değiştirmemelidir. Gerçekten dahili bir ID'ye ihtiyacınız varsa (kuyruk mesajı veya arka plan işi için), orijinali bir parent alanı olarak saklayın ki hikâye bağlantısı kaybolmasın.
Diğer yaygın bir boşluk kısmi loglamadır. Ekipler ID'yi ilk API'ye ekler ama worker süreçlerinde, zamanlanmış işlerde veya veritabanı erişim katmanında unuturlar. Sonuç: ölü bir uç—isteğin sisteme girişini görürsünüz ama sonra nereye gittiğini göremezsiniz.
ID her yerde olsa bile, her servis farklı bir alan adı veya format kullanıyorsa arama zor olur. Tek bir isim seçin ve frontend, API'ler ve loglar boyunca ona bağlı kalın (örneğin correlation_id). Ayrıca bir format seçin (çoğunlukla UUID) ve kopyala-yapıştırın çalışması için case-sensitive (büyük/küçük duyarlı) olarak ele alın.
İşler yanlış gittiğinde ID'yi kaybetmeyin. Bir API 500 veya doğrulama hatası döndürürse korelasyon ID'sini hata yanıtında (ve mümkünse yanıt başlığında) ekleyin. Kullanıcı bunu destek sohbetine yapıştırdığında ekip hemen tam yolu izleyebilsin.
Hızlı bir test: bir support personeli tek bir ID ile başlayıp ilgili tüm log satırlarını (hatalar dahil) takip edebiliyor mu?
Bu, destekten "sadece loglarda arayın" demeden önce bir akıl kontrolü olarak kullanın. Bu yalnızca her atlayış aynı kuralları takip ettiğinde çalışır.
correlation_id alanını yapılandırılmış olarak ekliyor.Zinciri koparmayan en küçük değişikliği yapın.
correlation_id'yi tutun ve daha fazla detay gerekiyorsa ayrı bir span_id ekleyin.Açığı yakalayan hızlı test: devtools'u açın, bir eylem tetikleyin, ilk isteğin correlation ID'sini kopyalayın, sonra aynı değeri ilişkili her API isteğinde ve ilgili her log satırında görüp görmediğinizi doğrulayın.
Korelasyon ID'leri, herkes aynı şekilde her seferinde kullandığında işe yarar. Korelasyon ID davranışını gönderim gerekliliğinin bir parçası haline getirin, isteğe bağlı bir logging ince ayarı değil.
Her yeni endpoint veya UI eylemi için küçük bir izlenebilirlik adımı ekleyin. ID'nin nasıl oluşturulacağı (veya yeniden kullanılacağı), akış sırasında nerede tutulacağı, hangi başlığın taşıyacağı ve her servis başlık eksik olduğunda ne yapacağı belgelenmelidir.
Hafif bir kontrol listesi genellikle yeterlidir:
correlation_id).Destek ekibinin hızlı ve tekrarlanabilir hata ayıklaması için basit bir betik de gerekir. ID'nin kullanıcılar için nerede görüneceğine karar verin (örneğin hata diyaloğunda "Hata ID'sini Kopyala" butonu) ve destek ekibinin ne isteyeceğini ve nerede arayacağını yazılı hale getirin.
Prodüksiyonda buna güvenmeden önce gerçek kullanım akışını benzeten bir aşamalı test çalıştırın: bir butona tıklayın, bir doğrulama hatası tetikleyin, sonra işlemi tamamlayın. Aynı ID'yi tarayıcı isteğinden, API loglarına, arka plan worker'larına ve veritabanı çağrı loglarına kadar izleyebildiğinizi doğrulayın.
Eğer Koder.ai üzerinde uygulamalar geliştiriyorsanız, korelasyon ID başlığı ve loglama konvansiyonlarını Planning Mode'a yazmak yardımcı olur; böylece oluşturulan React ön yüzleri ve Go servisleri varsayılan olarak uyumlu başlar.
Bir korelasyon ID'si, tarayıcı, API'ler, servisler ve worker'lar dahil olmak üzere tek bir kullanıcı eylemi veya iş akışıyla ilgili her şeyi etiketleyen ortak bir tanımlayıcıdır. Destek ekipleri tek bir ID ile tam zaman çizelgesini çekebilir ve hangi log satırlarının birbiriyle ilişkili olduğunu tahmin etmek zorunda kalmazlar.
Bir olayı uçtan uca hızlıca sorun giderirken korelasyon ID'si kullanın (örneğin “Pay tuşuna tıkladım ve başarısız oldu”). Oturum ID'si çok geniştir (birden fazla eylemi kapsar), istek ID'si ise çok dar—sadece tek bir HTTP isteğini tanımlar ve retry'lerde değişir.
En iyi varsayılan yer, kullanıcı eyleminin başladığı frontend'dir; form gönderildiğinde, butona tıklandığında veya çok adımlı bir akış tetiklendiğinde ID oluşturmak erken hikâyeyi korur (UI hataları, retry'ler, iptal edilen istekler gibi).
Kopyalanması kolay ve destek biletlerinde paylaşılması güvenli, UUID benzeri opak bir değer kullanın. ID'ye kişisel veri (kullanıcı adı, e-posta, sipariş numarası, zaman damgası vb.) koymayın; bu bağlamı ayrı, uygun gizlilik kontrollerine sahip log alanlarında saklayın.
Herkes için tek bir başlık ismi belirleyin ve her yerde aynı yapılandırılmış alan adıyla loglayın; örneğin X-Correlation-ID başlığı ve correlation_id log alanı. Tutarlılık, kesin isimden daha önemlidir çünkü destek ekibinin arayacağı tek, tahmin edilebilir bir şey olmalı.
Aynı kullanıcı eylemi devam ediyorsa retry'ler aynı korelasyon ID'sini kullanmalıdır; bu sayede loglar bağlantılı kalır. Kullanıcının daha sonra ayrı bir deneme başlatması durumunda yeni bir korelasyon ID'si oluşturun.
API giriş noktası, gelen başlığı kabul etmeli; başlık yoksa veya açıkça geçersizse yeni bir ID oluşturmalıdır. Ayrıca yanıt başlıklarında (ve mümkünse hata gövdelerinde) ID'yi geri döndürerek kullanıcıların veya destek ekiplerinin kopyalayıp paylaşmasını sağlayın.
İstek bağlamında korelasyon ID'sini tutun ve her alt hizmete kopyalayın; HTTP/gRPC çağrılarında ve kuyruklanan işlerde ID'yi gönderin. Orta uçta yeni bir korelasyon ID'si üretmekten kaçının; ekstra ayrıntı gerekiyorsa, zinciri bozmadan ayrıca bir iç span_id veya benzeri ekleyin.
Korelasyon ID'sini loglarda birincil yapılandırılmış alan olarak tutun, mesaj metninin içinde gömülü bırakmayın; böylece aranabilir ve filtrelenebilir olur. Hizmet adı, route, durum, süre ve kullanıcı için güvenli bir tanımlayıcı gibi alanlarla eşleştirin ve hata durumlarında da loglandığından emin olun.
Hızlı bir test: bir eylem tetikleyin, ilk istekteki veya hata ekranındaki korelasyon ID'sini kopyalayın ve aynı değerin ilişkili her istek başlığında ve her servis log satırında görünüp görünmediğini doğrulayın. Eğer ID worker'larda, retry'lerde veya hata yanıtlarında kayboluyorsa, orası düzeltilmesi gereken ilk yerdir.