Distributed tracing, correlation ID, span, event log, metrics, alerting, model ve prompt versioning

Satın alma ekibi yeni bir tedarik sözleşmesi yüklüyor. Yapay zekâ ajanı tarafları ve tarihleri çıkarıyor, otomatik yenileme maddesini riskli buluyor, kurum politikasını kontrol ediyor, hukuk ekibinden onay istiyor ve onay geldikten sonra ilgili gruba bir inceleme görevi açıyor.

Hukuk yöneticisi şu soruyu soruyor: Bu görev neden oluşturuldu, son tarih neden yedi gün sonrası seçildi ve neden bu gruba atandı?

Ekranda yalnızca nihai görev görünüyorsa cevap vermek zordur. Çünkü karar; tek bir model cevabından değil, belge çıkarımından, politika aramasından, model değerlendirmesinden, araç çağrısından, insan onayından ve veri tabanı kaydından oluşan bir zincirdir.

İzlenebilir ajan, yalnızca ne yaptığını kaydeden değil; hangi belge, model, prompt, araç sonucu ve insan onayıyla yaptığını kanıtlayabilen ajandır.

Bu bölümde tek bir sözleşme iş akışının izini süreceğiz. Amaç, teknik olmayan bir yöneticinin de bir yazılım ekibinin de aynı soruya cevap verebilmesini sağlamaktır: Sistem ne yaptı, neden yaptı, nerede bekledi, hangi sürümle yaptı ve gerektiğinde sorumluluk kimdeydi?

Gözlemlenebilirlik, her şeyi kaydetmek değildir

Observability (gözlemlenebilirlik), sistemin iç durumunu dışarıya verdiği sinyallerden anlayabilme yeteneğidir. OpenTelemetry bu sinyalleri traces (izler), metrics (ölçümler) ve logs (günlükler) olarak sınıflandırır. Aynı bağlamın servisler arasında taşınması, ayrı kayıtların tek bir hikâyede birleşmesini sağlar (OpenTelemetry, 2026a; 2026b).

Ancak yapay zekâ ajanlarında yalnızca teknik sağlık yetmez. Modelin hangi girdiyi kullandığı, hangi aracı neden seçtiği, hangi kaynaklara dayandığı, hangi insanın onay verdiği ve hangi sürümlerin çalıştığı da görünür olmalıdır.

Bunun karşılığı ham belgeyi, bütün prompt’u ve kişisel verileri sınırsız biçimde loglamak değildir. Doğru yaklaşım; gerekli kimlikleri, sürümleri, zamanları, durumları ve kanıt bağlantılarını kaydetmek; hassas içeriği maskelemek veya yalnızca yetkili incelemeye açmaktır.

Distributed tracing — dağıtık izleme nedir?

Şekil 1. Tek sözleşme süreci, aynı trace altında birbirine bağlı span’ler hâlinde izlenir. Her span bir adımın ne kadar sürdüğünü, hangi durumda bittiğini ve hata üretip üretmediğini gösterir.

Bir trace (iz), bir isteğin veya işlemin sistem boyunca izlediği yolun bütünüdür. Bir span ise bu yolun tek bir çalışma parçasıdır: PDF’den metin çıkarma, modele çağrı yapma, politika arama, onay bekleme veya görev oluşturma gibi.

Span kayıtlarında genellikle başlangıç ve bitiş zamanı, süre, durum, hata bilgisi, üst span kimliği ve işlemi açıklayan sınırlı öznitelikler bulunur. Parent–child ilişkisi sayesinde ‘görev oluşturma gecikti’ demekle kalmaz; gecikmenin model çağrısından mı, insan onayından mı yoksa görev API’sinden mi kaynaklandığı görülür.

OpenAI’ın ajan izleme dokümantasyonu da çalışmayı session, turn ve span düzeyinde ele alır; agent, generation, tool, handoff ve guardrail gibi adımlar ayrı span olarak kaydedilebilir. OpenTelemetry’nin üretken yapay zekâ yaklaşımı ise ajan span’inin altında model ve araç span’leri oluşturarak aynı nedensellik zincirini kurar (OpenAI, 2026; OpenTelemetry, 2026c).

Bir span hangi bilgileri taşımalıdır?

Alan	Örnek	Neden gerekir?
span adı	contract.risk.analyze	Adımın ne yaptığını düşük kardinaliteyle tanımlar.
trace / span / parent ID	4bf92f… / 7a21… / 2f91…	Adımı bütün iz ve üst işlemle bağlar.
başlangıç, bitiş, durum	09:42:11–09:42:14 / OK	Gecikme ve hata yerini gösterir.
ajan, model, prompt sürümü	risk-agent@3 / model-v3 / prompt@17	Davranış değişimini sürümle ilişkilendirir.
araç ve sonuç kimliği	task.create@5 / TSK-77108	Teknik çağrıyı gerçek iş nesnesine bağlar.
kaynak ve politika kimliği	madde 12.4 / HUK-PR-2026.04	Kararın dayandığı kanıtı gösterir.

Span adı sözleşme numarası gibi her istekte değişen değerler içermemelidir. Değişken değerler öznitelik olarak tutulur. Bu ayrım, ölçümlerin kontrolsüz etiket sayısıyla büyümesini ve izleme maliyetinin patlamasını önler.

Correlation ID — ilişkilendirme kimliği neden ayrıca gerekir?

Şekil 2. Trace ID tek teknik yürütmeyi gösterir; correlation veya workflow ID, saatler süren insan onayı ve farklı trace’ler dâhil bütün iş sürecini birbirine bağlar.

Trace ID çoğunlukla tek bir teknik yürütmenin kimliğidir. Oysa kurumsal işler bazen dakikalar veya günler sürer. Ajan onay ister, süreç bekler, kullanıcı daha sonra yanıt verir ve yeni bir servis çağrısı başlar. Bu yeni çağrı farklı bir trace ID taşıyabilir.

Correlation ID veya daha açık bir adla workflow ID, bu parçaları aynı iş yolculuğuna bağlar. Sözleşme örneğinde WF-2026-004821 kimliği; belge analizi, hukuk onayı ve görev oluşturma trace’lerinin tamamında korunur.

W3C Trace Context standardı, sistemler arası iz bağlamının traceparent ve tracestate başlıklarıyla taşınmasını tanımlar. Aynı standart, trace başlıklarına kişisel veya hassas bilgi konulmaması gerektiğini de vurgular. Bu nedenle kimlik; ad, e-posta veya sözleşme metni değil, anlamsız ve tahmin edilmesi güç bir değer olmalıdır (W3C, 2021).

Trace ID bir yürütmeyi; workflow ID bütün iş yolculuğunu anlatır.

Sözleşme iş akışının gerçek izi

Aşağıdaki kimlikler örnektir; amaç, bir inceleme ekranında hangi bağların görünmesi gerektiğini göstermektir:

workflow_id     = WF-2026-004821

trace_id        = 4bf92f3577b34da6a3ce929d0e0e4736

document_id     = SOZ-18452

document_hash   = sha256:9d8a…

agent_version   = contract-agent@3.2

model_version   = contract-risk-v3

prompt_version  = risk-analysis@17

policy_version  = HUK-PR-2026.04

approval_id     = APR-9301

task_id         = TSK-77108

1. Belge yüklenir. document_id ve değişmez dosya özeti alınır; trace ve workflow kimlikleri oluşturulur.
2. Metin çıkarılır. Kullanılan OCR veya parser sürümü, süre ve sayfa sayısı span’e yazılır.
3. Kurum politikası aranır. Bulunan politika sürümü, madde kimlikleri ve arama sonucu kaydedilir; ham metin yalnızca yetkili erişime açılır.
4. Model riski değerlendirir. Model, prompt, parametre, araç şeması, token kullanımı ve kaynak kimlikleri kayda alınır.
5. İnsan onayı istenir. Süreç bekleme durumuna geçer; karar veren kişi, rol, zaman ve gerekçe audit trail’e eklenir.
6. Görev aracı çağrılır. İstek kimliği, idempotency anahtarı, sonuç kodu ve oluşan task_id trace’e bağlanır.
7. İş akışı tamamlanır. Nihai durum, toplam süre ve kullanıcıya gösterilen karar özeti kaydedilir.

Trace, event log, metric ve audit trail neden ayrıdır?

Şekil 3. Aynı iş akışı dört farklı soruya cevap verir: yol, olay, eğilim ve sorumluluk. Güvenilir inceleme için bu kayıtlar birbirine bağlanmalı fakat birbirinin yerine kullanılmamalıdır.

Kayıt	Cevapladığı soru	Sözleşme örneği
Trace — iz	İstek hangi sırayla nerelerden geçti?	Politika araması 1,8 sn; görev API’si ikinci denemede başarılı.
Event log — olay günlüğü	Belirli anda ne oldu?	risk_detected, approval_requested, task_created.
Metrics — ölçümler	Sistem genelinde ne kadar oluyor?	p95 süre, hata oranı, onay bekleme süresi, token maliyeti.
Audit trail — denetim izi	Kim, hangi yetkiyle neyi değiştirdi?	Hukuk yöneticisi 13.58’de onayladı; görev 14.02’de açıldı.

Event log iş olaylarının kronolojisidir. Audit trail ise hesap verebilirlik taşır: aktör, yetki, önceki ve sonraki değer, gerekçe ve değişmez zaman kaydı gibi unsurları içerir. Trace teknik nedenselliği gösterir; audit trail işlemin hangi sorumlulukla yapıldığını gösterir.

Trace sistemin nasıl ilerlediğini; audit trail işlemin hangi yetki ve sorumlulukla yapıldığını gösterir.

Metrics — ölçümler neyi erken fark ettirir?

Tek bir başarılı trace sistemin sağlıklı olduğunu kanıtlamaz. Metrics, binlerce iş akışından sayısal eğilim üretir. Böylece bir prompt değişikliğinden sonra insan müdahalesinin artması veya yeni modelde görev oluşturma süresinin yükselmesi görülebilir.

Ölçüm	Ne anlatır?	Tek başına yetmez; çünkü…
Görev tamamlama oranı	İş akışlarının kaçı hedefe ulaştı?	Yanlış görev de tamamlanmış sayılabilir.
Araç hata oranı	API ve entegrasyonlar ne kadar bozuluyor?	Hata modelden değil dış sistemden gelebilir.
p50 / p95 gecikme	Tipik ve kötü uçtaki süre nedir?	İnsan bekleme süresi ayrı izlenmelidir.
İnsan müdahale oranı	Ne kadar iş otomatik tamamlanamıyor?	Yüksek riskli işlerde müdahale kasıtlı olabilir.
Token ve işlem maliyeti	Bir iş akışının kaynak tüketimi nedir?	Ucuz işlem doğru işlem anlamına gelmez.
Doğrulanmış hata oranı	Sonradan kontrol edilen kararların kaçı yanlış?	Gerçek etiket ve düzenli örnekleme gerekir.

Alerting — uyarı üretimi ne zaman anlamlıdır?

Şekil 4. Ham sinyaller ölçümlere, ölçümler eşik ve anomali kurallarına, kurallar ise sahibi ve ilk adımı belli uyarılara dönüşür.

Her model hatasında alarm üretmek kısa sürede alarm yorgunluğu yaratır. İyi uyarı, önemli bir riskin oluştuğunu veya oluşmak üzere olduğunu gösterir ve sahibine ilk güvenli adımı söyler.

• Onay kaydı olmadan görev oluşturma çağrısı yapıldıysa kritik uyarı üret.
• Görev aracının hata oranı beş dakikada yüzde 5’i aşarsa entegrasyon ekibini uyar.
• p95 analiz süresi belirlenen eşiği aşarsa model, retrieval ve dış servis span’lerini birlikte göster.
• Prompt veya model sürümü boş olan karar kaydı oluşursa iş akışını durdur ve kayıt eksikliği uyarısı üret.
• Aynı workflow için birden fazla task_id oluşursa mükerrer işlem alarmı ver.
• Token maliyeti sürüm değişiminden sonra olağan bandın dışına çıkarsa maliyet ve kaliteyi birlikte incele.

Model ve prompt versioning — sürümleme neden zorunludur?

Şekil 5. Bir kararın sürüm zarfı; belge, model, prompt, politika ve araç şeması kimliklerini aynı kayıt altında toplar.

‘Model olarak X kullanıldı’ ifadesi yeterli değildir. Aynı model adı arkasında sağlayıcı güncellemesi olabilir; prompt değişmiş, kurum politikası yenilenmiş veya araç şeması farklılaşmış olabilir. İnceleme için kararın bütün sürüm zarfı gerekir.

• Model: sağlayıcı, model kimliği, mümkünse sabit sürüm veya snapshot ve önemli üretim parametreleri.
• Prompt: prompt kimliği, değişmez sürümü veya hash’i; sistem talimatı ile görev şablonu ayrı sürümlenmelidir.
• Bilgi kaynağı: politika ve prosedür sürümü, retrieval dizini veya veri kümesi sürümü, kaynak parça kimlikleri.
• Araçlar: işlev adı, şema sürümü, entegrasyon sürümü ve yetki politikası.
• Koruma katmanı: guardrail, doğrulama ve iş kuralı sürümleri.

MLflow Prompt Registry değişmez prompt sürümleri, karşılaştırma, alias ve lineage özellikleri sunar; Model Registry de model sürümlerini ve hangi çalışma ile üretildiklerini izler. Buradaki önemli ilke üründen bağımsızdır: üretimde ‘latest’ kullanmak yerine kararı değişmez sürüm kimliklerine bağlamak gerekir (MLflow, 2026a; 2026b).

Sürümleme, aynı cevabı bire bir yeniden üretme garantisi değildir. Modellerde örnekleme, sağlayıcı altyapısı ve dış veriler değişebilir. Ama hangi bileşenlerin çalıştığını bilmek, kontrollü karşılaştırma ve olay incelemesi için vazgeçilmezdir.

Gizlilik: görünürlük ile ifşa arasındaki sınır

Sözleşme metnini, kişisel verileri ve prompt içeriğini her trace’e yazmak incelemeyi kolaylaştırıyor gibi görünür; fakat yeni bir veri sızıntısı yüzeyi oluşturur. OpenTelemetry’nin üretken yapay zekâ yaklaşımı da içerik yakalamanın büyük ve hassas olabileceğini, bu nedenle isteğe bağlı ve kontrollü tutulması gerektiğini belirtir (OpenTelemetry, 2026c).

• Trace başlıklarına kişi adı, e-posta, sözleşme numarası veya sır niteliğinde veri koymayın.
• Ham içerik yerine document_id, alan kimliği, sayfa/madde referansı ve kriptografik özet kullanın.
• Prompt ve model çıktısını varsayılan olarak maskeleyin; yalnızca yetkili olay incelemesinde açın.
• İzleme verisini şifreleyin, erişimleri ayrıca audit log’a yazın ve saklama sürelerini veri sınıfına göre belirleyin.
• Normal trace’lerde örnekleme yapılabilir; ancak audit olayları ve kritik yetki kararları örnekleme nedeniyle kaybolmamalıdır.

Bir inceleme ekranında ne görülmelidir?

Hukuk yöneticisi TSK-77108 görevini açtığında tek tıklamayla şu zincire ulaşabilmelidir:

• Görevin bağlı olduğu workflow ve trace kimlikleri.
• Belgenin kimliği, değişmez özeti ve kararın dayandığı madde referansları.
• Ajan, model, prompt, politika, retrieval ve araç sürümleri.
• Her span’in süresi, durumu, hata ve retry bilgisi.
• İnsan onayının aktörü, rolü, zamanı ve gerekçesi.
• Oluşan görev, kayıt ve mesaj gibi iş nesnelerinin kimlikleri.
• Kişisel veriler maskelenmiş olmak üzere karar özeti ve kanıt bağlantıları.

Asgari telemetri sözleşmesi

Bir ajan üretime alınmadan önce ekipler hangi alanların her çalışmada tutulacağını ortak bir telemetry contract ile tanımlamalıdır. Asgari liste şunları içerebilir:

Kategori	Zorunlu alanlar
Bağlam	trace_id, span_id, parent_span_id, workflow_id, session_id
İş nesnesi	document_id, approval_id, task_id; gerekirse değişmez hash
Ajan ve model	agent_id/version, provider, model_id/version, üretim parametreleri
Prompt ve bilgi	prompt_id/version/hash, policy_id/version, retrieval index ve source ID
Araç ve yürütme	tool name/version, schema version, idempotency key, status/error, retry count
Zaman ve maliyet	start/end/duration, token kullanımı, tahmini işlem maliyeti
İnsan kararı	actor/role, decision, timestamp, reason; erişimi kontrollü

Kurumsal uygulama için kontrol soruları

• Her ajan çalışması trace ve workflow kimlikleriyle uçtan uca bağlanıyor mu?
• İnsan onayıyla ayrılan asenkron adımlar aynı iş yolculuğunda birleşiyor mu?
• Model, prompt, politika, araç şeması ve guardrail sürümleri değişmez kimliklerle kaydediliyor mu?
• Her nihai iş nesnesinden karar izine geri gidilebiliyor mu?
• Trace, event log, metric ve audit trail görevleri birbirinden ayrıldı mı?
• Kritik işlemlerde onay kapısı ve yetki kontrolü trace üzerinde görünür mü?
• Alert kurallarının sahibi, önceliği ve ilk müdahale adımı belirli mi?
• Normal, hata ve yüksek riskli trace’ler için örnekleme politikası farklı mı?
• Audit olayları örnekleme nedeniyle kaybolmaktan korunuyor mu?
• Ham belge ve kişisel veriler yerine kimlik, hash ve maskeleme kullanılıyor mu?
• İzleme verisine erişim ayrıca kaydediliyor ve saklama süresi uygulanıyor mu?
• Yeni model veya prompt sürümü sonrası kalite, maliyet ve gecikme birlikte karşılaştırılıyor mu?

Kısa kavram sözlüğü

Distributed tracing — dağıtık izleme: Bir isteğin birden fazla servis ve bileşen boyunca izlediği yolu tek nedensellik zinciri olarak görme yöntemi.

Trace — iz: Bir iş veya isteğin uçtan uca teknik yürütmesi.

Span: Trace içindeki tek çalışma birimi; süre, durum ve üst-alt ilişkisi taşır.

Correlation ID — ilişkilendirme kimliği: Birden fazla trace ve bekleme aşamasını aynı iş sürecine bağlayan kimlik.

Event log — olay günlüğü: Belirli zamanda gerçekleşen iş veya sistem olaylarının kaydı.

Metrics — ölçümler: Çok sayıda çalışmadan elde edilen oran, toplam, dağılım ve eğilimler.

Alerting — uyarı üretimi: Ölçüm veya olay belirli risk koşulunu karşıladığında sorumlu kişiye eyleme dönük bildirim üretme.

Model / prompt versioning — sürümleme: Bir kararı üreten model, prompt ve ilişkili bileşenleri değişmez sürüm kimlikleriyle kaydetme.

Audit trail — denetim izi: Kim, ne zaman, hangi yetkiyle ve hangi değişikliği yaptı sorularına kanıt sağlayan kayıt zinciri.

Sonuç: açıklanabilir sonuçtan kanıtlanabilir sürece

Bir ajan doğru görev oluşturmuş olabilir. Ancak kurumun güveni yalnızca doğru görünen sonuca dayanamaz. Sonucun hangi belgeye, hangi politika sürümüne, hangi model ve prompt’a, hangi araç çağrısına ve hangi insan onayına dayandığı görülebilmelidir.

Dağıtık izleme teknik yolculuğu; correlation ID uzun iş sürecini; event log olayları; metrics eğilimleri; alerting müdahale gerektiren sapmaları; sürümleme ise davranış değişiminin kaynağını görünür kılar. Audit trail bütün bunlara yetki ve sorumluluk boyutunu ekler.

Amaç, mümkün olan her veriyi toplamak değildir. Amaç; bir karar sorgulandığında gerekli kanıtı bulabilecek, bir hata büyümeden fark edebilecek ve hassas bilgiyi gereksiz yere ifşa etmeyecek kadar ölçülü bir izlenebilirlik mimarisi kurmaktır.

Güvenilir ajan, yalnızca işi yapan değil; yaptığı işin izini geriye doğru kanıtlayabilen ajandır.

Bir sonraki DERİNLEŞME bölümünde

“Bir yapay zekâ ajanının kalitesi üretimde nasıl sürekli ölçülür ve bozulma nasıl fark edilir?”

DERİNLEŞME 18’de offline evaluation (çevrimdışı değerlendirme), online evaluation (çevrim içi değerlendirme), golden dataset (altın veri kümesi), regression test (gerileme testi), drift (sapma), human feedback (insan geri bildirimi) ve red teaming kavramlarını yine tek bir sözleşme iş akışı üzerinden inceleyeceğiz.

Yazar

Dr. Mert Dönerçark

Yapay Zekâ Araştırmacısı ve Yazılım Stratejisti

Yayın Destekçisi ve Şeffaflık Notu

Bu yayın, MicroDestek katkılarıyla hazırlanmaktadır. Yazılarımda zaman zaman örneklerine yer verdiğim KolayOfis, ContractFlow ve MicroDestek Yapay Zekâ Asistanı, görev yaptığım MicroDestek tarafından geliştirilmektedir. Paylaştığım değerlendirmeler ise akademik ve uygulamalı çalışmalarım doğrultusunda oluşturulmuş kişisel görüşlerimi yansıtmaktadır.

Kaynakça

• MLflow. (2026a). Prompt Registry. MLflow documentation. Bağlantı
• MLflow. (2026b). Model Registry. MLflow documentation. Bağlantı
• OpenAI. (2026). Tracing. OpenAI API documentation. Bağlantı
• OpenTelemetry. (2026a). Concepts. OpenTelemetry documentation. Bağlantı
• OpenTelemetry. (2026b). Signals. OpenTelemetry documentation. Bağlantı
• OpenTelemetry. (2026c). GenAI observability with OpenTelemetry. OpenTelemetry blog. Bağlantı
• OpenTelemetry. (2026d). Semantic conventions for generative AI systems. OpenTelemetry documentation. Bağlantı
• World Wide Web Consortium. (2021). Trace Context: W3C Recommendation. Bağlantı

Kaynaklara son erişim tarihi: 4 Kasım 2026