Log

ipucu

Bu doküman spesifik bir politikanın detaylı kullanımını anlatır. Eğer Apinizer politika yapısını ilk kez kullanıyorsanız veya politikaların genel çalışma prensiplerini öğrenmek istiyorsanız, öncelikle Politika Nedir? sayfasını okumanızı öneririz.

Genel Bakış

Amacı Nedir?

Log Politikası, mesaj işleme hattının (pipeline) herhangi bir noktasına yerleştirilerek o anki mesaj durumunun anlık görüntüsünü (snapshot) yakalar ve belirlenen konnektörlere gönderir.
Standart trafik loglamasından farklı olarak, pipeline'ın ara noktalarında (örneğin bir dönüştürme politikasından önce ve sonra) loglama yaparak mesaj değişikliklerini izlemeyi sağlar.
HTTP, WebSocket ve gRPC protokollerinde çalışır.
Birden fazla konnektöre aynı anda gönderim yapabilir.

Çalışma Prensibi

Politika Tetiklenmesi: Mesaj işleme hattında log politikasının sırası geldiğinde çalışır.
Anlık Görüntü Oluşturma: O anki mesaj durumu protokole özel olarak yakalanır (başlık, parametre, gövde bilgileri).
Konnektörlere Gönderim: Anlık görüntü, tanımlanan her konnektöre ayrı ayrı gönderilir.
Gizlilik Uygulama: Gizlilik ayarları etkinse, hassas veriler gönderimden önce işlenir (maskeleme, silme, hashleme, şifreleme).

Kullanım Alanları

Belirli pipeline aşamalarında mesaj durumunu izleme (politika öncesi/sonrası karşılaştırma)
Hata ayıklama ve sorun giderme için detaylı log toplama
Denetim ve uyumluluk gereksinimlerini karşılama
Harici sistemlere (SIEM, log analiz platformları) gerçek zamanlı veri gönderimi

Desteklenen Hedefler

Hedef	Protokol
Elasticsearch	REST/HTTP
Veritabanı (Oracle, MySQL/MariaDB, PostgreSQL, SQL Server, MongoDB)	JDBC / MongoDB Driver
Graylog	GELF
Webhook	HTTP POST
Syslog	Syslog Protocol
Kafka	Kafka Producer
RabbitMQ	AMQP

Protokol Desteği

Protokol	Başlık (Header)	Parametre	Gövde (Body)
HTTP	✓	✓	✓
WebSocket	✓	—	✓
gRPC	—	—	✓

bilgi

WebSocket ve gRPC protokollerinde başlık ve parametre bilgileri protokol yapısı gereği sınırlı olabilir.

Konfigürasyon Alanları

Genel Ayarlar

Alan	Açıklama
Ad	Politikanın tanımlayıcı adı
Açıklama	Politikanın amacını belirten açıklama
Aktif	Politikanın aktif/pasif durumu
Çalışma Modu	Senkron veya Asenkron çalışma modu (aşağıda detaylandırılmıştır)
Koşul	Politikanın ne zaman çalışacağını belirleyen koşul (isteğe bağlı)

Konnektör Seçimi

Politikanın log göndereceği konnektörleri seçebilirsiniz. Konnektörler, bağlantı tanımı üzerinden seçilir ve ortam bağımsız çalışır — aynı bağlantı tanımı farklı ortamlarda farklı konnektör örneklerine karşılık gelebilir.

bilgi

Global politika olarak işaretlenen tanımlar birden fazla ortamda kullanılabilir; her ortamda aynı bağlantı tanımına karşılık gelen konnektörün yapılandırılmış olması gerekir.

Loglanan Alanlar

Aşağıdaki alan gruplarından hangilerinin log kaydına dahil edileceğini belirleyebilirsiniz:

Alan Grubu	Açıklama
İstemciden Gelen İstek Başlıkları	İstemciden API Proxy'ye gelen istek başlık bilgileri
İstemciden Gelen İstek Parametreleri	İstemciden API Proxy'ye gelen istek parametreleri
İstemciden Gelen İstek Gövdesi	İstemciden API Proxy'ye gelen istek gövdesi
Hedefe Gönderilen İstek Başlıkları	API Proxy'den Backend API'ye gönderilen istek başlık bilgileri
Hedefe Gönderilen İstek Parametreleri	API Proxy'den Backend API'ye gönderilen istek parametreleri
Hedefe Gönderilen İstek Gövdesi	API Proxy'den Backend API'ye gönderilen istek gövdesi
Hedeften Gelen Yanıt Başlıkları	Backend API'den gelen yanıt başlık bilgileri
Hedeften Gelen Yanıt Gövdesi	Backend API'den gelen yanıt gövdesi
İstemciye Gönderilen Yanıt Başlıkları	İstemciye gönderilen yanıt başlık bilgileri
İstemciye Gönderilen Yanıt Gövdesi	İstemciye gönderilen yanıt gövdesi
Metadata	IP adresi, HTTP metodu, URI, port gibi istek metadata bilgileri
Metrikler	Süre, boyut, önbellek durumu gibi performans metrikleri

Gövde Loglama Modu

Mod	Açıklama
Tam (Full)	Gövde verisi tamamen loglanır
Kısmi (Partial)	Gövde verisi belirtilen maksimum boyuta kadar loglanır. Boyut aşıldığında veri kesilir

Çalışma Modları

Mod	Gönderim	Hata Durumu	Pipeline Etkisi
Senkron (varsayılan)	Sıralı, tamamlanana kadar beklenir	Hata fırlatılır	Pipeline kırılır
Asenkron	Arka planda, beklenmez	Hata loglanır, yutulur	Pipeline devam eder

uyarı

Senkron modda konnektör hatası pipeline'ı kırar ve istemciye hata döner. Üretim ortamında kesintisiz çalışma gerekiyorsa asenkron modu tercih edin.

ipucu

Asenkron modda konnektör hatası oluştuğunda hata bilgisi uygulama loglarına yazılır, ancak istemci isteği etkilenmez.

Veri Yapısı

Log politikası, standart API trafik loglarından farklı hafif bir veri yapısı kullanır. Aşağıdaki tabloda gönderilen alanlar ve Elasticsearch/veritabanı karşılıkları listelenmiştir.

Alan Adı	Kısa Ad (ES/JSON)	Tip	Açıklama
Timestamp	@timestamp	Date	Log kaydının oluşturulma zamanı
Korelasyon ID	aci	String	Apinizer istek izleme ID'si
Ortam ID	ei	String	Gateway ortam tanımlayıcısı
API Proxy ID	api	String	API Proxy tanımlayıcısı
API Proxy Adı	apn	String	API Proxy adı
API Proxy Metot ID	apmi	String	API Proxy metot tanımlayıcısı
API Proxy Metot Adı	apmn	String	API Proxy metot adı
Kullanıcı/Anahtar	uok	String	Doğrulanmış kullanıcı adı veya API anahtarı
HTTP Durum Kodu	sc	Number	HTTP yanıt durum kodu
Sonuç Tipi	rt	String	İşlem sonucu (SUCCESS, ERROR vb.)
Hata Tipi	et	String	Hata tipi (varsa)
İstek Başlıkları	fcrh	List	Anahtar-değer çifti olarak istek başlıkları
İstek Parametreleri	fcrp	List	Anahtar-değer çifti olarak sorgu parametreleri
İstek Gövdesi	fcrb	String	İstek gövde içeriği
Pipeline Konumu	cr	String	Log politikasının yerleştirildiği pipeline bölgesi
Atama Seviyesi	cl	String	Log politikasının bağlandığı hiyerarşi seviyesi

Örnek JSON Çıktı

{
  "@timestamp": "2026-03-31T12:30:45.123Z",
  "aci": "550e8400-e29b-41d4-a716-446655440000",
  "ei": "env-production-001",
  "api": "proxy-payment-api",
  "apn": "Payment API",
  "apmi": "method-create-payment",
  "apmn": "POST /payments",
  "uok": "merchant-api-key-123",
  "sc": 200,
  "rt": "SUCCESS",
  "fcrh": [
    { "k": "Content-Type", "v": "application/json" },
    { "k": "Authorization", "v": "Bearer eyJhbGciOi..." },
    { "k": "X-Request-ID", "v": "req-abc-123" }
  ],
  "fcrp": [
    { "k": "currency", "v": "TRY" },
    { "k": "lang", "v": "tr" }
  ],
  "fcrb": "{\"amount\": 150.00, \"merchantId\": \"M-001\"}",
  "cr": "FROM_CLIENT",
  "cl": "API_PROXY_METHOD"
}

bilgi

Başlık ve parametre alanlarındaki her bir giriş k (key) ve v (value) çiftinden oluşur. Bu yapı Elasticsearch'te nested tip olarak indekslenir.

Pipeline Konumu (`cr`) Değerleri

Değer	Açıklama
`FROM_CLIENT`	İstemciden gelen isteğin işlendiği ilk pipeline aşaması
`TO_BACKEND`	İsteğin backend'e iletilmeden önceki son pipeline aşaması
`FROM_BACKEND`	Backend yanıtının işlendiği ilk pipeline aşaması
`TO_CLIENT`	Yanıtın istemciye gönderilmeden önceki son pipeline aşaması

Atama Seviyesi (`cl`) Değerleri

Değer	Açıklama
`API_PROXY_GROUP`	Politika bir proxy grubuna bağlıdır; gruptaki tüm proxy'lere uygulanır
`API_PROXY`	Politika doğrudan bir API Proxy'ye bağlıdır
`API_PROXY_METHOD`	Politika belirli bir API Proxy metoduna bağlıdır

Elasticsearch Entegrasyonu

Elasticsearch'te log politikası verileri için ayrı bir index template oluşturulmalıdır. Bu template standart API trafik log template'inden farklıdır ve yalnızca log politikasının gönderdiği alanları içerir.

uyarı

Log politikası verileri için Elasticsearch index template'i ve ILM politikası Apinizer UI'dan otomatik oluşturulmaz. Aşağıdaki adımları Elasticsearch üzerinde manuel olarak uygulamanız gerekir.

Adım 1: ILM Politikası Oluşturma

Index yaşam döngüsü yönetimi için bir ILM politikası oluşturun. Aşağıdaki örnek 30 GB veya 1 günde rollover yapan ve 30 gün sonra silen bir politika oluşturur. Değerleri ihtiyacınıza göre ayarlayın.

PUT _ilm/policy/apinizer-log-policy-capture-ilm
{
  "policy": {
    "phases": {
      "hot": {
        "actions": {
          "rollover": {
            "max_size": "30gb",
            "max_age": "1d"
          }
        }
      },
      "delete": {
        "min_age": "30d",
        "actions": {
          "delete": {}
        }
      }
    }
  }
}

Adım 2: Index Template Oluşturma

Aşağıdaki komutu Elasticsearch Kibana Dev Tools veya curl kullanarak çalıştırın. Template data stream desteği içerir.

uyarı

Template'teki alan tipleri, log politikasının gönderdiği JSON yapısıyla birebir eşleşmelidir. Alan tiplerini değiştirmeyin.

PUT _index_template/apinizer-log-policy-capture-template
{
  "index_patterns": ["apinizer-log-policy-capture*"],
  "data_stream": {},
  "template": {
    "settings": {
      "index": {
        "lifecycle": {
          "name": "apinizer-log-policy-capture-ilm"
        },
        "number_of_shards": 1,
        "number_of_replicas": 0,
        "refresh_interval": "5s"
      }
    },
    "mappings": {
      "properties": {
        "@timestamp": {
          "type": "date",
          "format": "yyyy-MM-dd'T'HH:mm:ss.S'Z'||yyyy-MM-dd'T'HH:mm:ss.SS'Z'||yyyy-MM-dd'T'HH:mm:ss.SSS'Z'"
        },
        "aci": {
          "type": "keyword"
        },
        "ei": {
          "type": "keyword"
        },
        "api": {
          "type": "keyword"
        },
        "apn": {
          "type": "keyword"
        },
        "apmi": {
          "type": "keyword"
        },
        "apmn": {
          "type": "keyword"
        },
        "uok": {
          "type": "keyword",
          "ignore_above": 50
        },
        "sc": {
          "type": "short"
        },
        "rt": {
          "type": "keyword",
          "ignore_above": 7
        },
        "et": {
          "type": "keyword",
          "ignore_above": 75
        },
        "fcrh": {
          "type": "nested",
          "properties": {
            "k": {
              "type": "keyword"
            },
            "v": {
              "type": "keyword"
            }
          }
        },
        "fcrp": {
          "type": "nested",
          "properties": {
            "k": {
              "type": "keyword"
            },
            "v": {
              "type": "keyword"
            }
          }
        },
        "fcrb": {
          "type": "text"
        },
        "cr": {
          "type": "keyword"
        },
        "cl": {
          "type": "keyword"
        }
      }
    }
  }
}

Adım 3: Data Stream Oluşturma

Template oluşturulduktan sonra, ilk veri geldiğinde data stream otomatik oluşur. Manuel oluşturmak için:

PUT _data_stream/apinizer-log-policy-capture

Konnektör Yapılandırması

Elasticsearch konnektörünün Index Adı alanına apinizer-log-policy-capture girin. Bu isim, template'teki index_patterns ile eşleşmelidir.

bilgi

Farklı bir index adı kullanmak istiyorsanız template'teki index_patterns alanını buna göre güncelleyin. Örneğin proje bazlı ayrıştırma için apinizer-log-policy-capture-proje-adi kullanabilirsiniz.

Veritabanı Entegrasyonu

Veritabanı konnektörü, her log politikası yakalamasını hedef ilişkisel veritabanındaki log_PolicyCapture tablosuna tek bir satır olarak yazar. Desteklenen veritabanı tipleri Oracle, MySQL/MariaDB, PostgreSQL ve SQL Server'dır. MongoDB için koleksiyon ilk yazımda otomatik oluşturulur — manuel kurulum gerekmez.

uyarı

İlişkisel veritabanları için log_PolicyCapture tablosu otomatik oluşturulmaz — konnektörü etkinleştirmeden önce tabloyu manuel olarak oluşturmanız gerekir. Desteklenen her veritabanı tipi için CREATE TABLE komutu, önerilen indeksler ve bölümleme (partitioning) rehberi için bakınız: Apinizer Log Tabloları Oluşturma Komutları.

bilgi

correlation_id kolonu aynı çağrının istek ve yanıt satırlarını birbirine bağlar. Log politikası birden fazla pipeline aşamasına yerleştirildiğinde (örneğin FROM_CLIENT ve TO_CLIENT), kayıtlar correlation_id üzerinden join edilerek bir işlem uçtan uca izlenebilir. Bu nedenle bu kolon üzerindeki indeks şiddetle önerilir.

ipucu

Yüksek trafikli API'lerde, veritabanı yazma gecikmesinin istek pipeline'ını bloke etmemesi için log politikasını Asenkron modda yapılandırmanızı öneririz.

Gizlilik Ayarları

Politika seviyesinde gizlilik ayarları yapılandırarak hassas verilerin log kaydına yazılmadan önce işlenmesini sağlayabilirsiniz.

İşlem	Açıklama
Maskeleme (Mask)	Hassas veriyi kısmen gizler (ör: `****1234`)
Silme (Delete)	Hassas veriyi tamamen kaldırır
Hashleme (Hash)	Hassas veriyi tek yönlü hash değerine dönüştürür
Şifreleme (Encrypt)	Hassas veriyi şifreler

bilgi

Gizlilik ayarları iki seviyede uygulanır: önce politika seviyesindeki ayarlar, sonra konnektör seviyesindeki ayarlar. Her iki seviye de etkinse, her ikisi de sırasıyla uygulanır.

Maskeleme, veri konnektörlere gönderilmeden önce uygulanır. Konnektör seviyesindeki gizlilik ayarları ayrı ve bağımsız olarak uygulanır. Bu özellik GDPR gibi veri koruma gereksinimlerini karşılamak için kullanılabilir.

Kullanım Senaryoları

Senaryo	Açıklama	Önerilen Mod
Dönüştürme öncesi/sonrası karşılaştırma	Bir dönüştürme politikasından önce ve sonra log politikası ekleyerek mesaj değişikliklerini izleme	Asenkron
Hata ayıklama (Debug)	Belirli bir politikanın girdi ve çıktısını incelemek için pipeline'a geçici log noktası ekleme	Senkron
Denetim kaydı	Hassas API'lerde her isteğin tam kaydını tutma	Asenkron
Çoklu hedef loglama	Aynı mesajı Elasticsearch ve Kafka'ya aynı anda gönderme	Asenkron
Koşullu loglama	Yalnızca belirli bir başlık değeri veya yol ile eşleşen istekleri loglama	Asenkron

İlgili Sayfalar

Politikayı Silme

Bu politikanın silinmesi ve kullanımda olduğu durumda yapılacak işlemler için Politika Nedir? sayfasına bakınız.

Politikayı Dışa/İçe Aktarma

Bu politikanın dışa aktarma adımları ve mevcut seçenekleri için Politika Nedir? sayfasına bakınız.

Politikayı API'ye Ekleme

Bu politikayı API'lere ekleme süreci için Politika Yönetimi sayfasındaki Akışa Politika Ekleme bölümüne bakınız.

Sonraki Adımlar

Script Politikası

Özel script ile veri dönüştürme

API Çağrısı Politikası

Pipeline içinde harici API çağrısı

Genel Bakış​

Amacı Nedir?​

Çalışma Prensibi​

Kullanım Alanları​

Desteklenen Hedefler​

Protokol Desteği​

Konfigürasyon Alanları​

Genel Ayarlar​

Konnektör Seçimi​

Loglanan Alanlar​

Gövde Loglama Modu​

Çalışma Modları​

Veri Yapısı​

Örnek JSON Çıktı​

Pipeline Konumu (cr) Değerleri​

Atama Seviyesi (cl) Değerleri​

Elasticsearch Entegrasyonu​

Adım 1: ILM Politikası Oluşturma​

Adım 2: Index Template Oluşturma​

Adım 3: Data Stream Oluşturma​

Konnektör Yapılandırması​

Veritabanı Entegrasyonu​

Gizlilik Ayarları​

Kullanım Senaryoları​

İlgili Sayfalar​

Politikayı Silme​

Politikayı Dışa/İçe Aktarma​

Politikayı API'ye Ekleme​

Sonraki Adımlar​

Genel Bakış

Amacı Nedir?

Çalışma Prensibi

Kullanım Alanları

Desteklenen Hedefler

Protokol Desteği

Konfigürasyon Alanları

Genel Ayarlar

Konnektör Seçimi

Loglanan Alanlar

Gövde Loglama Modu

Çalışma Modları

Veri Yapısı

Örnek JSON Çıktı

Pipeline Konumu (`cr`) Değerleri

Atama Seviyesi (`cl`) Değerleri

Elasticsearch Entegrasyonu

Adım 1: ILM Politikası Oluşturma

Adım 2: Index Template Oluşturma

Adım 3: Data Stream Oluşturma

Konnektör Yapılandırması

Veritabanı Entegrasyonu

Gizlilik Ayarları

Kullanım Senaryoları

İlgili Sayfalar

Politikayı Silme

Politikayı Dışa/İçe Aktarma

Politikayı API'ye Ekleme

Sonraki Adımlar