İzleme ve Tekrar Oynatma
Genel Bakış
AI izleme (trace) özelliği, AI Gateway'den geçen isteklerin uçtan uca zincirini (trace grubu / DAG) gerçek zamanlı olarak oluşturur ve şu yetenekleri sunar:
- Trace Detayı — bir isteğin tüm adımlarını (politikalar, yönlendirme kararı, sağlayıcı isteği ve yanıtı) tek ekranda inceleyin
- Tekrar Çalıştırma (Replay) — yakalanmış bir trace'i yeni ve gerçek bir istek olarak yeniden çalıştırın
- APM Entegrasyonu — kullanım metriklerini OpenTelemetry GenAI semantiği ve Prometheus üzerinden dışa aktarın
İzleme verisine erişim kendi yetki kapsamıyla korunur (analitik görüntüleme yetkisi + proje kapsamı) ve kayıtlar kısa bir saklama süresi sonunda otomatik olarak temizlenir.
Etkin veri saklama profili Standart dışındaysa (Gövde Yok veya Kalıcı Kayıt Yok) trace başlatma isteği reddedilir — yetkili bir kullanıcı bile bu proxy/proje/kurulum için trace açamaz. Zaten çalışan bir trace'i durdurmak (stop) bu kısıttan etkilenmez.
Live Trace'i Açma
İzleme varsayılan olarak kapalıdır. Bir LLM Gateway için açmak için:
LLM Gateway'i açın ve Trace sekmesine gidin. Gateway'in en az bir ortama deploy edilmiş olması gerekir.
İzlenecek ortamı seçin. İsterseniz yalnız eşleşen trafiği izlemek için bir filtre (özel sorgu) seçin; varsayılan Tüm Trafik'tir.
Başlat'a tıklayın. Live Trace 5 dakika sonra otomatik durur; Durdur'a tıklayarak daha erken de durdurabilirsiniz.
Live Trace açıkken Apinizer, izlenen isteklerin ham istek, yanıt ve akış parçalarını da yakalar.
Trace Grubu (DAG) Nasıl Oluşur?
Live Trace açıkken, her istek girişinde benzersiz bir trace kimliği üretilir ve isteğin tüm yaşam döngüsü boyunca taşınır:
- Ana istek ile alt-çağrılar (örn. bir ajan aracının başka bir LLM Gateway'i çağırması, veya bir A2A görev zinciri) aynı trace grubu kimliği altında ilişkilendirilir
- Her alt-adım, bir üst (parent) trace kimliğine referans verir — böylece adımlar arasında ebeveyn-çocuk ilişkisi kurulur
Bu, özellikle MCP araç çağrıları ve A2A ajan görevleri gibi çok-adımlı senaryolarda tek bir kullanıcı isteğinin tüm alt-işlemlerinin birbirine bağlı şekilde izlenmesini sağlar.
Trace Detayı
LLM Gateway'in Trace sekmesinde bir isteği açtığınızda detayında şunları görürsünüz:
- İsteğin istemciden her politikadan geçerek sağlayıcıya ulaşan akışı; her adımın süresi ve durumu (başarılı/hata/atlandı)
- Her politikadan önce ve sonra istek ve yanıt gövdeleri
- Yönlendirme kararı, sağlayıcıya gönderilen istek ve sağlayıcının yanıtı
Politikanın İç Adımları
Önbelleğe erişen AI politikaları (semantik önbellek, token hız sınırı) iki ayrı yaşam döngüsü geçişinde gerçek iş yapar: istek fazındaki karar (önbellek sorgusu, token rezervasyonu) ve yanıt tamamlandıktan sonra çalışan akış-sonu geçişi (yanıtın önbelleğe yazılması, rezervasyonun gerçekte tüketilen token ile işlenmesi).
İki geçiş de gerçek birer çalışmadır; bu yüzden akışta her biri kendi düğümüyle görünür — trace, sadeleştirilmiş bir özet değil gerçekte çalışanı gösterir. İkinci düğüm ↺ rozeti taşır; üzerine geldi ğinizde rozet fazın adını değil o geçişte yapılan işi söyler ("Akış sonu — yanıt önbelleğe yazıldı", "Akış sonu — token rezervasyonu kapatıldı"). Düğüme tıkladığınızda detay panelinde aynı etiketle birlikte "Neden ikinci kayıt?" satırı çıkar; böylece "mükerrer politika" değil "ikinci faz" olarak okunur.
Token hız sınırı (proxy koruma limiti), semantik önbellek araması ve döngü koruması yönlendirme aşamasında çalışır. Bu kurallar, sağlayıcı ve model kesinleştikten ve model erişim kontrolü geçildikten sonra çalışır. İstek hattında bu üç politika Deferred to the model decision in routing nedeniyle atlandı olarak görünür. Süre-ölçüm görünümünde de bu satır atlandı olarak işaretlenir. Gerçek çalışma, yönlendirmede ikinci bir kayıt olarak görünür. Bu davranış yalnız LLM Gateway'leri için geçerlidir; MCP ve A2A proxy'leri etkilenmez.
İkinci düğümün çıkıp çıkmayacağı isteğe bağlıdır:
| Durum | İkinci düğüm |
|---|---|
| Semantik önbellek ıskalama (MISS) | Var — yanıt akış sonunda önbelleğe yazılır |
| Semantik önbellek isabet (HIT) | Yok — yeniden önbelleklenecek bir şey olmadığı için akış-sonu geçişi hiç tetiklenmez |
| Token hız sınırı | Var, yapılandırılan politika sayısı kadar — rezervasyon işlenir ya da serbest bırakılır |
Üst bardaki Çalıştırma Detayları düğmesi, düğümün arkasındaki önbellek çağrılarını açar: işlem (RESERVE / RECONCILE / RELEASE / GET / PUT), kova (bucket), önbellek anahtarı, sonuç ve süre. Bu davranış, API proxy izleme ekranındaki API Call politikasının detay penceresiyle aynıdır.
Trace Sırası Develop'tan Neden Farklı Olabilir
Trace, gerçek çalışma sırasını gösterir ve LLM Gateway'lerde bu, Develop ekranında dizdiğiniz sıra ile her zaman aynı olmaz. Gateway, istek hattını çalıştırmadan önce savunmacı bir yeniden sıralama uygular; böylece yanlış bir sıralama doğruluğu ya da bir korumayı sessizce bozamaz:
- Prompt Template, Prompt Decorator'dan önce çalışır — Decorator, Template'in ürettiği
messages[]dizisine ekleme yapar. - Prompt Template / Prompt Decorator, RAG Injection ve tüm guard/cache politikalarından önce çalışır — bunların tam kurulmuş prompt'u görmesi gerekir, ham istemci gövdesini değil.
- RAG Injection, İstem Koruması, Bağlam Bütünlüğü, DLP Koruması ve Semantik Önbellek'ten önce çalışır — RAG'in enjekte ettiği içerik korumalar tarafından taranmalı ve önbellek anahtarına girmelidir; aksi halde koruma etkisiz kalır ve önbellek zehirlenebilir.
Yani bir düğüm trace'te Develop'takinden daha erken görünüyorsa istek yanlış işlenmiş değildir — gateway sırayı düzeltmiştir. Develop ekranı bu kurallardan biri ihlal edildiğinde sizi uyarır: hem politikaları sürükle-bırak ile yeniden sıraladığınızda, hem de akış ekranı bu sırayla yüklendiğinde (yeni bir politika eklenip geri dönüldüğünde de). Konfigürasyonu düzelttiğinizde uyarı kesilir ve iki ekran birbiriyle örtüşür.
Semantik önbellek için bu pencere, kararın kendisinin (isabet/ıskalama, eşleşme kaynağı — birebir ya da vektör, benzerlik değeri, önbellek anahtarı, TTL, model) yanı sıra önbellek konuşmasını da gösterir: isteğin prompt metni ve isabet durumunda önbellekten sunulan, yazma fazında ise önbelleğe kaydedilen yanıt gövdesi. Böylece "bu istek neden önbellekten döndü" ya da "önbelleğe hangi yanıt yazıldı" sorusu, akıştaki ham istek/yanıt gövdelerini karşılaştırmaya gerek kalmadan tek pencereden cevaplanır.
Tekrar Çalıştırma (Replay)
Replay, yakalanmış bir trace'i yeniden çalıştırır: gateway, trace'in sağlayıcıya giden isteğini aynı politika zincirinden tekrar geçirir ve sonucu yeni bir trace olarak kaydeder. Bir müşteri şikayetini yeniden üretmek ya da yapılandırma değişikliği sonrası davranışı karşılaştırmak için kullanın.
Replay saklanan yanıtın tekrar oynatılması değil, canlı bir istektir:
- LLM sağlayıcısına gerçek bir çağrı yapılır; bu yüzden token, maliyet ve kota harcanır ve korumalar yeniden çalışır.
- Orijinal isteğin bir yan etkisi varsa (örn. dış sisteme yazan bir araç çağrısı) bu yan etki tekrar gerçekleşebilir. Replay'i salt-okunur ya da analiz amaçlı isteklerde kullanın.
- İsteği çalıştıracak gateway'in ortamını seçmeniz gerekir. O ortamdaki yalnız bir gateway örneği isteği çalıştırır.
- Yalnız Live Trace açıkken kaydedilen trace'ler yeniden çalıştırılabilir, çünkü istek gövdesini yalnız onlar saklar. Başka bir kaydın replay'i reddedilir.
- Replay için projede AI Geliştirme – Yönet yetkisi gerekir. Trace'leri okumanızı sağlayan AI analitik görüntüleme yetkisi yeterli değildir.
Replay, Manager REST API üzerinden kullanılabilir (POST /api/ai-trace/{id}/replay?projectId=...&environmentName=...). Trace sekmesinde Replay düğmesi yoktur.
Metrik ve Trace Aktarımı: OpenTelemetry ve Prometheus
UI'daki trace görünümlerinin ötesinde, AI Gateway kullanım sinyalleri (token, maliyet, gecikme, koruma sonucu) kendi gözlemlenebilirlik altyapınıza iki tamamlayıcı yoldan ulaşır:
- Prometheus — gateway'in mevcut
apinizer_ai_*sayaç/zamanlayıcıları (sağlayıcı, model, proje, durum etiketleriyle), aşağıdaki ayardan bağımsız her zaman açık. - Doğal OpenTelemetry (OTLP) dışa aktarımı — opsiyonel, agent gerektirmeyen ürün-native bir özellik: tüm trafik için W3C
traceparentyayılımı ile retrospektif bir span ağacı (SERVER + deneme-başına CLIENT + istek/yanıt span'leri) ve özellikle AI trafiği için GenAI semantik-kural katmanı (gen_ai.*,apinizer.ai.*) — doğrudan üründen OTLP collector'ınıza aktarılır, javaagent gerekmez. İçerik yakalama (span'lerde prompt/completion) varsayılan olarak kapalıdır.
Tam öznitelik/metrik referansı, kurulum adımları ve indirilebilir bir Grafana dashboard'u için OpenTelemetry sayfasına bakın.
Sonraki Adımlar
Ajan görevlerinin trace zincirindeki izini görün
Araç çağrısı zincirlerini izleyin
Performans ve gecikme metriklerini inceleyin
Koruma tetiklenmelerini trace zincirinde ilişkilendirin
Doğal OTLP dışa aktarımını yapılandırın ve Grafana dashboard'unu içe aktarın