Korelasyon ID'leri uçtan uca: bir kullanıcı eylemini loglarda izleme

Korelasyon ID'leri neden destek için önemlidir

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:

• Korelasyon ID: bir eylemle ilgili her şeyi gruplar (örneğin, "Ayarları kaydet").
• İstek ID: tek bir HTTP isteğini tanımlar. Retry'ler yeni istek ID'leri üretir.
• Trace ID: dağıtık izleme araçları tarafından kullanılır; benzer amaç, genellikle izleme kütüphaneleri tarafından üretilir.
• Oturum ID: birçok eylem boyunca bir kullanıcı oturumunu tanımlar; tek bir olayı debug etmek için çok geniştir.

İ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.

Korelasyon ID konvansiyonlarını belirleyin

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.

Frontend'te ID oluşturma (pratik yaklaşım)

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.

Bir iş akışı için ID oluşturun ve saklayı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.

İş akışının yaptığı her isteğe ekleyin

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.

ID'yi API'leriniz boyunca güvenilir şekilde iletin

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:

• Tek bir ortak istemci yardımcı öğesi her isteğe başlığı ekler.
• Retry'ler aynı eylem için aynı ID'yi kullanır.
• Herhangi bir gövde/sorgu yedeği tek belgelenmiş alan adını kullanır.
• WebSocket mesajları açık bir correlationId alanı içerir.

API giriş noktası davranışını ayarlayın

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:

• İstekten X-Correlation-ID (veya seçtiğiniz başlık) oku.
• Eksik veya geçersizse yeni bir ID oluşturup istek bağlamına ekle.
• Her yanıta, hatalar dahil, X-Correlation-ID ekle.
• JSON hata döndürürken ID'yi gövdede yansıt.

Ö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"
  }
}

Korelasyon ID'sini backend servisleri boyunca aktarın

İ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.

İnsanların kullanabileceği loglara ID ekleyin

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.

ID'yi kullanılabilir kılan log alanları

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 method
• status ve duration_ms
• kullanıcı için güvenli bir tanımlayıcı (örneğin account_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.

Başlangıç, başarı ve hata durumlarında ne loglanmalı

Her istek için uzun bir döküm yerine birkaç güçlü iz bırakmayı hedefleyin.

• Başlangıç: korelasyon ID, route, güvenli kullanıcı tanımlayıcı ve ana girdilerin özeti.
• Başarı: korelasyon ID, durum, süre ve kısa bir sonuç (örneğin rows=12).
• Hata: korelasyon ID, hata türü, güvenli bağlam ve nerede oluştuğu (handler, bağımlılık).

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.

Örnek: bir kullanıcı raporunu UI'den veritabanına kadar izlemek

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:

• Nedeni düzeltin (örneğin timeout'u ayarlayın ve güvenli bir retry ekleyin).
• Kullanıcıya gösterilen hataların korelasyon ID'si içerdiğinden emin olun.
• Aynı hata desenini farklı ID'lerle arayın ve yeni logları izleyin.
• ID'nin tüm atlamaları (worker'lar ve kuyruk mesajları dahil) koruduğunu doğrulayın.

Yaygın hatalar ve nasıl önlenir

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.

"İsimlendirme kaosu" sorunundan kaçının

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?

Uçtan uca kapsama için hızlı kontrol listesi

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.

Geçmesi gereken kontroller

• Her yerde (frontend, gateway, API'ler, worker'lar) tek bir ID formatı ve tek bir başlık adı kullanılıyor.
• Frontend, kullanıcı eylemi başlangıcında ID oluşturuyor (veya alıyor) ve eylem bitene kadar sabit tutuyor.
• API giriş noktası eksikse ID oluşturuyor ve her yanıtın başlığında döndürüyor.
• Her backend servis, istekle ilişkili loglarda correlation_id alanını yapılandırılmış olarak ekliyor.
• On-call kişi tek bir ID'yi log aramasına yapıştırıp edge isteği, auth, servis çağrıları, veritabanı işlemi ve retry'leri birkaç dakika içinde görebiliyor.

Herhangi bir kontrol başarısızsa, şöyle düzeltin

Zinciri koparmayan en küçük değişikliği yapın.

• ID'ler uçuş ortasında değişiyorsa, iç servislerin yeni ID üretmesini durdurun. Orijinal correlation_id'yi tutun ve daha fazla detay gerekiyorsa ayrı bir span_id ekleyin.
• Loglarda alan eksikse, mühendislerin hatırlaması gerekmeden middleware ile log ekleyin.
• Destek ID'yi alamıyorsa, UI'nin hata ekranlarında bunu göstermesini ve gateway'in her yanıtta bunu yansıtmasını sağlayın.

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.

Sonraki adımlar: bunu geliştirme sürecinize entegre edin

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:

• Frontend: her kullanıcı eylemi için bir ID üretin veya yeniden kullanın ve o eylem için yapılan tüm API çağrılarına ekleyin.
• API giriş noktası: başlığı kabul etsin, doğrulasın veya üretip yanıtın içinde yansıtsın.
• Backend: ID'yi downstream servislere ve işlere aktarın, loglara ekleyin.
• Logging: uygulamalar ve servisler arasında alan adını tutarlı tutun (örneğin correlation_id).
• İncelemeler: ID'nin loglarda göründüğünü kanıtlayan testleri olmayan PR'ları reddedin.

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.