Trace
Tracing (İzleme), API Proxy'lerinizin mesaj işleme akışını gerçek zamanlı olarak izlemenizi ve analiz etmenizi sağlar. Trace işlemi API Proxy bazında yapılır ve her API Proxy için ayrı ayrı aktifleştirilir.
Bu modül özellikle:
- Politikaların nasıl çalıştığını anlamak
- Performans sorunlarını tespit etmek
- Hata ayıklama (debugging) yapmak
- İstek/yanıt akışını incelemek
- Dönüşümleri (transformations) doğrulamak
için kullanılır.
Her API Proxy için ayrı ayrı trace oturumu başlatabilirsiniz
Her politikanın çalışmasını adım adım izleyebilir ve log kayıtlarını görüntüleyebilirsiniz
Zamanlama metriklerini analiz edebilir ve darboğazları tespit edebilirsiniz
Hataları kolayca tespit edebilir ve kök neden analizini yapabilirsiniz
Trace işlemi API Proxy bazında yapılır. Log satırına tıkladığınızda sağdan trace detay çekmesi açılır; zaman dağılımı, Client–Gateway–API haritası ve politika öncesi/sonrası paneller burada yer alır. Tüm adımlar için Adım Adım İzleme sayfasına bakabilirsiniz.
Trace Modunu Başlatma
Trace modu, her API Proxy için ayrı ayrı başlatılır. API Proxy'nin kendi sayfasından trace modunu aktifleştirebilirsiniz.
Ön Koşullar
Trace modunu başlatmadan önce:
İzlemek istediğiniz API Proxy'nin en az bir Ortam'a yüklenmiş olması gerekir
Trace yapmak istediğiniz API Proxy'nin detay sayfasına gidin
API Proxy'nin yüklenmiş olduğu Ortam'lardan hangisi için izleme modu açılacaksa o Ortam seçilir
Başlat (Start) tuşuna tıklayarak trace modunu aktifleştirin
Ortam seçiminin yanındaki filtre alanından Custom Query ile sadece istenen veriler üzerinden özel olarak trace edilebilir.
Trace modu aktifleştirildiğinde:
- Log kayıtlarının içeriği detaylı incelemeye izin verecek şekilde genişletilir
- Log kayıtları MongoDB konfigürasyon veri tabanına yazılır
- İşletilen tüm politikalar için ayrıntılı log kayıtları oluşturulur
- Mod durdurulana ya da 5 dakika sonunda platform tarafından otomatik olarak kapatılana kadar bu şekilde saklanmaya devam eder
Trace Kayıtları
Trace modu aktifleştirildikten sonra, API Proxy'ye gelen istekler otomatik olarak izlenir ve detaylı kayıtlar oluşturulur.
Yenile Sil
Görüntülenmekte olan log kayıtları otomatik olarak güncellenmez. Yeni kayıtları görmek için Logları Yenile (Refresh Logs) tuşunu kullanın.
Tabloda görünen log kayıtlarının her birisi, istemciden bu API Proxy'e gelen istek ve o isteğe verilen yanıt mesajına aittir.
API Çağrı Politikasının log kaydı ayrı olarak tutulduğu için aynı isteğe ait çift log gözükür. Bunların ilk akıştaki mesajın önceki ve sonraki halidir, ikinci ise API Çağrısından çıkan istek ve yanıt mesajıdır.
Trace Listesi
Trace listesinde her bir kayıt için aşağıdaki bilgiler görüntülenir:
| Bilgi | Açıklama |
|---|---|
| Timestamp | İsteğin geldiği tarih ve saat |
| Method | HTTP metodu (GET, POST, PUT, DELETE, vb.) |
| Path / Endpoint | İstek path'i ve endpoint adı |
| Status Code | Yanıt durum kodu (200, 404, 500, vb.) |
| Duration | Toplam işlem süresi (ms) |
| Policies | Çalıştırılan politika sayısı |
| Correlation ID | İsteğe özgü korelasyon kimliği |
API Çağrı Politikası kullanıldığında, aynı isteğe ait çift log kaydı görünür:
- Ana akıştaki mesajın önceki ve sonraki hali
- API Çağrısından çıkan istek ve yanıt mesajı
Trace İşlemleri
Her trace kaydı için aşağıdaki işlemler yapılabilir:
- Detaylı Görüntüleme
- JSON Formatında Görüntüleme
- İndirme
- Hızlı Test
İncelenmek istenen istek mesajına ait satırın sonundaki tuşlardan ilki, o mesajın log kayıtlarını görüntüleyen bir pencere açar.
Açılan pencerede loglar, mesaj akışına ilişkin bölümlere ayrılmıştır. İncelenmek istenen bölümün adına tıklandığında bu alana ilişkin log kayıtları görüntülenir. Varsayılan olarak Genel Bakış bölümü açıktır.
Detaylı Görüntüleme tuşunun yanındaki tuş log kayıtlarını JSON formatında görüntüler.
JSON görünümündeki anahtar değerler okunabilir şekilde yazılmıştır. Örneğin:
- "apiProxyId" değeri log kaydında "api" şeklinde tutulur
- Gerçek log formatı için API Trafiği Log Kaydı Veri Yapısı sayfasına bakabilirsiniz
Apinizer, adım adım izleme modundayken, API Proxy için işletilen bütün politikalar için de ayrıntılı bir şekilde log kayıtları oluşturur. İndirme seçeneği, istek bazlı olarak oluşturulan bütün log kayıtlarını topluca indirme olanağı sağlar.
Log kaydının veri büyüklüğü 500KB'den büyükse, Detaylı Göster ve JSON Formatında Görüntüle seçenekleri kapalı olur. Bu durumda kayıt indirilerek incelenmelidir.
İlgili satırdaki Hızlı Test tuşu, gönderilen isteğin yeniden gönderilerek anında test edilebileceği şekilde biçimlendirilmiş olarak Test Konsolunu açar.
Hızlı Test tuşunun görünmesi için genel ayarlarda etkinleştirilmelidir.
Politika Akışını İzleme
Apinizer'ın adım adım izleme modundayken API Proxy için işletilen politikalara ilişkin tuttuğu ayrıntılı log kayıtlarını görüntülemek için Seç tuşuna tıklanır.
Tabloda bir satıra tıkladığınızda veya Seç ile kaydı seçtiğinizde sağdan trace detay çekmecesi açılır. Üstte zaman dağılımı ve Client → Gateway → API işlem haritası yer alır; haritada istek hattı (üst sıra) ve yanıt hattı (alt sıra) üzerindeki politika düğümleri, varsa API Proxy Grup politikaları da dahil olmak üzere işletilme sırasına göre gösterilir.
Düğümlerde başarı için yeşil onay, hata veya blok için !, atlanan politika için soluk görünüm ve S rozeti kullanılır. ‹ Back / Next › veya doğrudan düğüme tıklayarak adımlar arasında gezersiniz. Ayrıntılı anlatım için Adım Adım İzleme sayfasına bakın.
- Başarılı Akış
- Başarısız Akış
Tüm adımların başarılı işlendiği örnek: çekmede zaman çubuğu, harita ve Client adımında istek/yanıt panelleri.
Hata durumunda (örneğin politika reddi, yönlendirme veya backend 404) haritada ilgili düğümlerde kırmızı ! görünebilir; Client adımında istemciye giden yanıtta HTTP durum kodu ve JSON fault gövdesi gibi ayrıntılar okunur.
Hata oluştuktan sonra çalışması beklenen adımlar haritada eksik kalabilir veya yürütülmemiş görünebilir; istemciye hata yanıtı döner.
Politika Execution Detayları
Pre-flow Politikaları
İstek geldiğinde ilk olarak işletilen politikalar:
- Politika Adı: Çalıştırılan politikanın adı
- Execution Time: Politikanın çalışma süresi (ms)
- Status: Başarılı / Başarısız durumu
- Changes: Politikanın mesajda yaptığı değişiklikler (header, body, variable değişiklikleri)
Örnekler: Kimlik doğrulama, rate limiting, IP kontrolü
Route Step (Yönlendirme)
Backend API'ye yönlendirme adımı:
- Selected Upstream: Seçilen upstream target
- Load Balancing Decision: Load balancing algoritması kararı
- Connection Time: Backend'e bağlanma süresi (ms)
- Backend Response Time: Backend'in yanıt süresi (ms)
- Retry/Failover: Retry veya failover durumu
Post-flow Politikaları
Backend'den yanıt geldikten sonra işletilen politikalar:
- Politika Adı: Çalıştırılan politikanın adı
- Execution Time: Politikanın çalışma süresi (ms)
- Status: Başarılı / Başarısız durumu
- Changes: Yanıt mesajında yapılan değişiklikler
Örnekler: Response transformation, cache writing, logging
Fault Handler
Hata durumunda çalıştırılan politikalar:
- Error Type: Hata türü (authentication, routing, policy, vb.)
- Error Message: Hata mesajı
- Handler Policies: Çalıştırılan hata yakalayıcı politikalar
- Final Response: İstemciye döndürülen son yanıt
Fault Handler sadece hata oluştuğunda çalışır ve hata yanıtını özelleştirmenizi sağlar.
Politikaya Özel Yürütme Detayları (Execution Details)
Belirli politika tiplerinde, trace çekmecesinin politika düğüm bar'ında Execution Details butonu görünür. Bu buton, seçilen politikanın türüne göre özelleştirilmiş modal pencere açar; modal, politikanın çalışma süreci hakkında domain-spesifik ayrıntıları accordion'lar halinde gösterir.
Execution Details Modalı Desteği:
| Politika Tipi | Gösterilen Detaylar |
|---|---|
| Cache (Önbellekleme) | Operation (LOOKUP/POPULATE/INVALIDATE), Cache Key, Hit/Miss sonucu, Source/Target Variable adları, TTL değeri, Cache Connection durumu |
| API Call (REST API Çağrısı) | Cache hit/miss durumu (varsa), HTTP method ve URL, Request/Response body özeti, Response status code, execution time (ms) |
| Backend API Authentication | Authenticated flag (true/false), Extracted username / roles listesi, Full HTTP call detayları (method, URL, header'lar), Backend yanıt status |
| JOSE Key Fetch (Dinamik Anahtar Getirme) | Mode (VALIDATION / IMPLEMENTATION), Key cache hit/miss, Key extraction path (JSONPath/XPath), HTTP endpoint call detayları |
| Client Ban | Banned flag, Ban kaynağı (IP/Credential/threshold), Remaining ban time (kalan saniye), Cache lookup sonucu |
| API Based Throttling | Current count / limit, Time window, Allowed/Blocked karar, Cache key ve lookup sonucu |
| API Based Quota | Current count / quota, Period end timestamp, Allowed/Blocked karar, Cache key ve lookup sonucu |
| Business Rule | Per-action execution listesi: action type, operator, condition result, input values, output values, execution time (ms), hata varsa hata mesajı |
Kullanım:
- Trace çekmecesinde politika düğümünü seçin
- Düğüm bar'ında (politika adı yanında) Execution Details butonu varsa tıklayın
- Modal, politika-spesifik accordion'larla açılır
- Kapatmak için modalın dışına tıklayın veya X düğmesine basın
Not: Request hattı (pre-flow) ve Yanıt hattı (post-flow) politikalarının her ikisinde de Execution Details butonu gösterir ise, aynı politika her iki tarafta da çalıştırılmış demektir.
Detaylı Log Kayıtları
Bir log satırı seçildiğinde açılan çekmece, mesaj akışının başarılı olup olmadığını harita ve üst bilgilerle özetler; seçilen düğüme göre alt panelde tablolar ve gövdeler gösterilir. Genel görünüm örneği — harita, özet satırı ve istek başlıkları:
Aşağıda aynı çekmece içinde sık kullanılan adımlar ve önerilen görseller özetlenmiştir (tam akış Adım Adım İzleme sayfasındadır).
İstemci (Client) adımı
Haritada Client düğümü seçildiğinde sol sütunda istemciden gelen istek (HTTP Info, başlıklar, parametreler, gövde), sağ sütunda istemciye giden yanıt görüntülenir.
Politika adımı (Before / After)
Haritada bir politika düğümüne tıkladığınızda yürütme bilgisi ve Before / After akordeonları ile mesajın politika öncesi ve sonrası karşılaştırılır.
Backend API ve yönlendirme
Hedef (API) özeti, Routing tablosu (genişletilmiş satır; yönlendirme için bkz. HTTP Yönlendirme) ve hedeften gelen yanıt sırayla aşağıdaki görsellerle örneklenir.
İstek/Yanıt Karşılaştırma
Trace modu, mesajın akış boyunca nasıl değiştiğini gösterir:
Her politika için mesajın önceki ve sonraki halini karşılaştırabilirsiniz
Dönüşüm (transformation) politikalarının etkisini görebilirsiniz
Eklenen, değiştirilen veya silinen header'ları görebilirsiniz
JSON/XML dönüşümlerini ve içerik değişikliklerini görebilirsiniz
Performans Analizi
Trace modu, performans sorunlarını tespit etmek için detaylı zamanlama metrikleri sağlar.
Zamanlama Metrikleri (Timing Metrics)
Her trace kaydı için aşağıdaki metrikler görüntülenir:
| Metrik | Açıklama |
|---|---|
| Total Duration | İsteğin giriş-çıkış süresi toplamı (ms) |
| Pre-flow Duration | Pre-flow politikalarının toplam çalışma süresi |
| Route Duration | Backend'e bağlanma ve yanıt alma süresi |
| Backend Duration | Backend API'nin yanıt süresi (net) |
| Post-flow Duration | Post-flow politikalarının toplam çalışma süresi |
| Gateway Overhead | Apinizer Gateway'in eklediği süre (Total - Backend) |
Gateway Overhead yüksekse, politika optimizasyonu yapılabilir. Backend Duration yüksekse, backend API optimize edilmelidir.
Politika Performans Analizi
Politikaların performansını analiz etmek için:
En uzun süre alan politikaları belirleyebilir ve optimize edebilirsiniz
Çalıştırılan toplam politika sayısını görebilir, gereksiz politikaları kaldırabilirsiniz
Her politikanın ortalama çalışma süresini izleyebilirsiniz
Politikaların sırasını değiştirerek performansı artırabilirsiniz
Optimizasyon Önerileri:
- Cache Politikası: Backend çağrılarını azaltmak için cache kullanın
- Conditional Flow: Gereksiz politikaları koşullu olarak atlayın
- Script Optimizasyonu: Script politikalarında yavaş işlemleri optimize edin
- Transformation: Gereksiz transformation'ları kaldırın
Backend Performans Metrikleri
Backend API'nin performansını izlemek için:
| Metrik | Açıklama |
|---|---|
| Connection Time | Backend sunucusuna TCP bağlantı süresi |
| SSL Handshake Time | HTTPS bağlantısı için SSL handshake süresi |
| Response Time | Backend'in yanıt oluşturma süresi |
| Total Backend Time | Connection + Response toplam süresi |
| Backend Status | Backend çağrısının başarı durumu |
| Retry/Failover Count | Retry veya failover yapılma sayısı |
Yüksek Connection Time backend sunucusunun yavaş veya ağ sorunlu olduğunu gösterir. Yüksek Response Time ise backend API'nin optimize edilmesi gerektiğini gösterir.
Kullanım Senaryoları
Senaryo 1: Performans Sorunu Tespiti
Durum: Bir API Proxy'nin yanıt süreleri beklenenden yüksek.
API Proxy sayfasından trace modunu aktifleştirin
Trace kayıtlarında yavaş istekleri (örn. >1000ms) bulun
Seç tuşu ile politika akışını görüntüleyin ve en yavaş politikaları tespit edin
- Backend API yavaş mı? → Backend optimize edilmeli
- Politikalar yavaş mı? → Script/transformation optimize edilmeli
- Database sorgusu yavaş mı? → Cache kullanılabilir
Tespit edilen sorunları çözün ve trace ile tekrar test edin
Senaryo 2: Hata Ayıklama
Durum: Bazı istekler 500 hatası veriyor ve nedeni bilinmiyor.
API Proxy sayfasından trace modunu aktifleştirin
Trace kayıtlarında 5xx hatalarını bulun
Seç tuşu ile politika akışını görüntüleyin ve kırmızı işaretli politikayı bulun
- Politikaya gelen mesajı inceleyin (Öncesi)
- Hata mesajını okuyun
- Detaylı log kayıtlarını inceleyin
- Veri formatı yanlış mı?
- Header eksik mi?
- Script hatası mı?
- Backend ulaşılamıyor mu?
Sorunu düzeltin ve trace ile tekrar test edin
Senaryo 3: Transformation Doğrulama
Durum: JSON to XML transformation'ının doğru çalışıp çalışmadığını kontrol etmek.
API Proxy sayfasından trace modunu aktifleştirin
Test Console'dan örnek bir JSON request gönderin
Seç tuşu ile politika akışını görüntüleyin ve transformation politikasına tıklayın
- Before: Gelen JSON mesajı
- After: Dönüştürülmüş XML mesajı
- Dönüşümün doğru olup olmadığını kontrol edin
Backend API log kayıtlarında giden mesajın XML formatında ve doğru olduğunu doğrulayın
Senaryo 4: Conditional Flow Testi
Durum: Koşullu politikaların doğru çalışıp çalışmadığını test etmek.
API Proxy sayfasından trace modunu aktifleştirin
- Premium user için istek
- Normal user için istek
- Misafir için istek
Seç tuşu ile politika akışını görüntüleyin ve hangi politikaların çalıştığını görün
- Condition expression neydi?
- Değerlendirme sonucu ne oldu?
- Doğru politikalar mı çalıştı?
Yanlış koşulları düzeltin ve tekrar trace ile test edin
En İyi Uygulamalar
Trace Kullanımı
- Geliştirme sırasında sürekli trace edin
- Yeni politikalar eklerken mutlaka trace ile test edin
- API değişikliklerini trace ile doğrulayın
- Production'da sadece gerektiğinde trace aktifleştirin
- Trace otomatik olarak 5 dakika sonra kapanır
- Performans etkisini göz önünde bulundurun
- Ortam seçiminin yanındaki filtre alanından Custom Query ile filtreleme yapın
- Sadece ilgili endpoint'leri trace edin
- Gereksiz trace kayıtlarını minimize edin
- Her API Proxy için ayrı ayrı trace başlatın
- İlgili API Proxy'nin sayfasından trace modunu aktifleştirin
- Trace kayıtları MongoDB'de saklanır
Performans İzleme
Performans Baseline Oluşturun:
- Normal koşullarda API'nin ortalama yanıt süresini ölçün
- Her politikanın ortalama çalışma süresini kaydedin
- Baseline'dan sapmaları izleyin ve alarm kurun
Düzenli İzleme:
- Haftada bir performans trace çalıştırın
- Trend analizleri yapın
- Yavaşlamaları erken tespit edin
Optimizasyon Döngüsü:
- Trace ile darboğazları tespit edin
- Optimizasyon yapın
- Trace ile iyileşmeyi doğrulayın
- Sonuçları dokümante edin
Hata Ayıklama
Tekrarlanabilir Test Senaryoları:
- Trace başlatmadan önce test senaryolarını hazırlayın
- Aynı test verisini kullanarak tutarlı sonuçlar alın
- Edge case'leri test edin
Sistematik Yaklaşım:
- Sorunu izole edin (hangi endpoint, hangi koşulda?)
- Trace ile detaylı bilgi toplayın
- Kök neden analizini yapın
- Düzeltme yapın
- Trace ile doğrulayın
- Süreci dokümante edin
Öncesi/Sonrası Karşılaştırması:
- Her politika için giriş/çıkış mesajlarını karşılaştırın
- Beklenmeyen değişiklikleri tespit edin
- Transformation doğruluğunu kontrol edin
İlgili Kaynaklar
API Proxy bazında trace işlemleri
API test ve debug konsolu
Politikaları yönetme ve yapılandırma
Log kayıt ayarlarını yapılandırma
Mesaj akışı ve politika çalıştırma hakkında bilgi
Conditional flow hakkında detaylı bilgi