Loglama

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ış

Loglama politikası, API Gateway pipeline’inin istenilen noktasında mesajın anlık durumunu (başlıklar, parametreler, gövde, kullanıcı bilgisi, hata durumu vb.) yakalar ve yapılandırılmış konnektörlere gönderir. Standart API trafik loglamasından farklı olarak, pipeline’ın herhangi bir aşamasına yerleştirilebilir ve sadece ilgili alanları içeren hafif bir veri yapısı kullanır.

Kullanım Alanları

Pipeline’ın belirli aşamalarında mesaj durumunu izlemek (politika öncesi/sonrası karşılaştırma)
Hata ayıklama ve sorun giderme için detaylı log toplamak
Denetim ve uyumluluk gereksinimlerini karşılamak
Harici sistemlere (SIEM, log analiz platformları) gerçek zamanlı veri göndermek

Desteklenen Hedefler

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

Çalışma Modu

Mod	Davranış
Senkron	Log gönderimi tamamlanana kadar pipeline bekler. Gönderim hatası pipeline’ı durdurur.
Asenkron	Log gönderimi arka planda yapılır. Pipeline kesintisiz devam eder. Hatalar sadece loglanır.

Yapılandırma Alanları

Alan	Zorunlu	Varsayılan	Açıklama
Konnektör Seçimi	Evet	-	Log verisinin gönderileceği bir veya birden fazla konnektör
Çalışma Modu	Hayır	Senkron	Senkron veya Asenkron gönderim
Korelasyon Kimliği	Hayır	Aktif	İstek izleme kimliğini dahil eder
Ortam Bilgisi	Hayır	Aktif	Gateway ortam bilgisini dahil eder
API Proxy Bilgisi	Hayır	Aktif	API Proxy ve metot bilgilerini dahil eder
Kullanıcı Bilgisi	Hayır	Aktif	Kullanıcı adı veya API anahtarını dahil eder
HTTP Bağlam Bilgisi	Hayır	Aktif	HTTP durum kodunu dahil eder
Sonuç Bilgisi	Hayır	Aktif	İşlem sonucu ve hata tipini dahil eder
Başlıklar	Hayır	Aktif	İstek başlıklarını dahil eder
Parametreler	Hayır	Aktif	Sorgu parametrelerini dahil eder
Gövde	Hayır	Aktif	İstek gövdesini dahil eder
Gövde Modu	Hayır	Tam	Tam gövde veya kısmi gövde (bayt sınırı ile)
Gövde Bayt Sınırı	Hayır	-	Kısmi modda maksimum bayt sayısı
Gizlilik	Hayır	Pasif	Hassas verileri maskeleme

Veri Yapısı

Loglama politikası, standart API trafik loglarından farklı ve daha 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
Zaman Damgası	@timestamp	Tarih	Log kaydının oluşturulma zamanı
Korelasyon Kimliği	aci	Metin	Apinizer istek izleme kimliği
Ortam Kimliği	ei	Metin	Gateway ortam tanımlayıcısı
API Proxy Kimliği	api	Metin	API Proxy tanımlayıcısı
API Proxy Adı	apn	Metin	API Proxy adı
API Proxy Metot Kimliği	apmi	Metin	API Proxy metot tanımlayıcısı
API Proxy Metot Adı	apmn	Metin	API Proxy metot adı
Kullanıcı/Anahtar	uok	Metin	Kimliği doğrulanmış kullanıcı adı veya API anahtarı
HTTP Durum Kodu	sc	Sayı	HTTP yanıt durum kodu
Sonuç Tipi	rt	Metin	İşlem sonucu (SUCCESS, ERROR vb.)
Hata Tipi	et	Metin	Hata tipi (varsa)
İstek Başlıkları	fcrh	Liste	Anahtar-değer çiftleri olarak istek başlıkları
İstek Parametreleri	fcrp	Liste	Anahtar-değer çiftleri olarak sorgu parametreleri
İstek Gövdesi	fcrb	Metin	İstek gövde içeriği
Pipeline Konumu	cr	Metin	Loglama politikasının yerleştirildiği pipeline bölgesi
Ekleme Kapsamı	cl	Metin	Loglama politikasının eklendiği hiyerarşi seviyesi

Örnek JSON Çıktısı

{
  "@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"
}

Başlık ve parametre alanlarındaki her bir girdi, k (anahtar) ve v (değer) çiftlerinden oluşur. Bu yapı, Elasticsearch’te nested tipinde 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 aşama
`FROM_BACKEND`	Backend’den gelen yanıtın işlendiği ilk aşama
`TO_CLIENT`	Yanıtın istemciye gönderilmeden önceki son aşama

Ekleme Kapsamı (`cl`) Değerleri

Değer	Açıklama
`API_PROXY_GROUP`	Politika bir proxy grubuna eklenmiş; gruptaki tüm proxy’leri kapsar
`API_PROXY`	Politika doğrudan bir API Proxy’ye eklenmiş
`API_PROXY_METHOD`	Politika belirli bir API Proxy metoduna eklenmiş

Elasticsearch Entegrasyonu

Loglama politikasının verilerini Elasticsearch’e göndermek için ayrı bir index template oluşturulmalıdır. Bu template, standart API trafik log template’inden farklıdır ve sadece loglama politikasının gönderdiği alanları içerir.

Loglama politikası verileri için Elasticsearch index template’i ve ILM politikası Apinizer arayüzünden otomatik oluşturulmaz. Aşağıdaki adımları Elasticsearch üzerinde manuel olarak uygulamanız gerekmektedir.

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ün sonra rollover yapan ve 30 gün sonra silen bir politikadır. Değerleri ihtiyacınıza göre ayarlayabilirsiniz.

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 ile çalıştırın. Template, data stream desteği ile birlikte gelir.

Template’deki alan tipleri, loglama 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 isterseniz:

PUT _data_stream/apinizer-log-policy-capture

Konnektör Yapılandırması

Elasticsearch konnektörünün Index Name alanına apinizer-log-policy-capture yazın. Bu isim, template’deki index_patterns ile eşleşmelidir.

Farklı bir index adı kullanmak isterseniz, template’deki index_patterns alanını da buna uygun şekilde güncelleyin. Örneğin, proje bazlı ayırım için apinizer-log-policy-capture-projectname kullanabilirsiniz.

Veritabanı Entegrasyonu

Loglama politikası verilerini ilişkisel veritabanına (MySQL/MariaDB veya Oracle) göndermek için aşağıdaki tablo yapısını oluşturmanız gerekmektedir.

Veritabanı konnektörü kullanmadan önce hedef veritabanında bu tabloyu oluşturmanız gerekmektedir. Tablo otomatik oluşturulmaz.

Oracle
MySQL/MariaDB
PostgreSQL
SQL Server

CREATE TABLE log_PolicyCapture (
  id VARCHAR2(255) PRIMARY KEY,
  log_timestamp TIMESTAMP,
  correlation_id VARCHAR2(255),
  environment_id VARCHAR2(255),
  api_proxy_id VARCHAR2(255),
  api_proxy_name VARCHAR2(255),
  proxy_method_id VARCHAR2(255),
  proxy_method_name VARCHAR2(255),
  username_or_key VARCHAR2(255),
  status_code NUMBER(10),
  result_type VARCHAR2(255),
  error_type VARCHAR2(255),
  from_client_ro_header CLOB,
  from_client_ro_param CLOB,
  from_client_ro_body CLOB,
  capture_region VARCHAR2(50),
  capture_location VARCHAR2(50)
);

CREATE TABLE log_PolicyCapture (
  id VARCHAR(255) PRIMARY KEY,
  log_timestamp TIMESTAMP NULL,
  correlation_id VARCHAR(255),
  environment_id VARCHAR(255),
  api_proxy_id VARCHAR(255),
  api_proxy_name VARCHAR(255),
  proxy_method_id VARCHAR(255),
  proxy_method_name VARCHAR(255),
  username_or_key VARCHAR(255),
  status_code INT,
  result_type VARCHAR(255),
  error_type VARCHAR(255),
  from_client_ro_header TEXT,
  from_client_ro_param TEXT,
  from_client_ro_body LONGTEXT,
  capture_region VARCHAR(50),
  capture_location VARCHAR(50)
);

CREATE TABLE log_PolicyCapture (
  id VARCHAR(255) PRIMARY KEY,
  log_timestamp TIMESTAMP,
  correlation_id VARCHAR(255),
  environment_id VARCHAR(255),
  api_proxy_id VARCHAR(255),
  api_proxy_name VARCHAR(255),
  proxy_method_id VARCHAR(255),
  proxy_method_name VARCHAR(255),
  username_or_key VARCHAR(255),
  status_code INTEGER,
  result_type VARCHAR(255),
  error_type VARCHAR(255),
  from_client_ro_header TEXT,
  from_client_ro_param TEXT,
  from_client_ro_body TEXT,
  capture_region VARCHAR(50),
  capture_location VARCHAR(50)
);

CREATE TABLE log_PolicyCapture (
  id NVARCHAR(255) PRIMARY KEY,
  log_timestamp DATETIME2,
  correlation_id NVARCHAR(255),
  environment_id NVARCHAR(255),
  api_proxy_id NVARCHAR(255),
  api_proxy_name NVARCHAR(255),
  proxy_method_id NVARCHAR(255),
  proxy_method_name NVARCHAR(255),
  username_or_key NVARCHAR(255),
  status_code INT,
  result_type NVARCHAR(255),
  error_type NVARCHAR(255),
  from_client_ro_header NVARCHAR(MAX),
  from_client_ro_param NVARCHAR(MAX),
  from_client_ro_body NVARCHAR(MAX),
  capture_region NVARCHAR(50),
  capture_location NVARCHAR(50)
);

Kolon	Açıklama
id	Kayıt kimliği
log_timestamp	Log kaydının oluşturulma zamanı
correlation_id	Korelasyon kimliği
environment_id	Ortam kimliği
api_proxy_id	API Proxy kimliği
api_proxy_name	API Proxy adı
proxy_method_id	Metot kimliği
proxy_method_name	Metot adı
username_or_key	Kullanıcı adı veya API anahtarı
status_code	HTTP yanıt kodu
result_type	İşlem sonucu
error_type	Hata tipi
from_client_ro_header	İstemciden gelen başlıklar (JSON)
from_client_ro_param	İstemciden gelen sorgu parametreleri (JSON)
from_client_ro_body	İstemciden gelen istek gövdesi
capture_region	Politikanın çalıştığı pipeline aşaması: `FROM_CLIENT` (İstemciden Gelen), `TO_BACKEND` (Arka Uca Giden), `FROM_BACKEND` (Arka Uçtan Gelen), `TO_CLIENT` (İstemciye Giden)
capture_location	Politikanın tanımlandığı seviye: `API_PROXY_GROUP` (Grup), `API_PROXY` (Proxy), `API_PROXY_METHOD` (Metot)

Başlık ve parametre alanları (from_client_ro_header, from_client_ro_param) JSON formatında saklanır. Her kayıt, anahtar-değer çiftlerinden oluşan bir dizi içerir.

Önerilen İndeksler

Log kayıtları zamanla büyük hacimlere ulaşabileceğinden, sorgu performansını artırmak için aşağıdaki indeksleri oluşturmanız önerilir. correlation_id kolonu üzerindeki indeks özellikle önemlidir. Loglama politikası pipeline’ın farklı noktalarına (örneğin FROM_CLIENT ve TO_CLIENT) yerleştirildiğinde, aynı isteğe ait istek ve yanıt kayıtları aynı correlation_id değerini paylaşır. Bu sayede istek ve yanıt kayıtları correlation_id üzerinden birleştirilerek bir işlemin uçtan uca izlenmesi sağlanır.

Oracle
MySQL/MariaDB
PostgreSQL
SQL Server

CREATE INDEX idx_logpolicy_correlation ON log_PolicyCapture(correlation_id);
CREATE INDEX idx_logpolicy_timestamp ON log_PolicyCapture(log_timestamp);
CREATE INDEX idx_logpolicy_proxy ON log_PolicyCapture(api_proxy_id);
CREATE INDEX idx_logpolicy_region ON log_PolicyCapture(capture_region);

CREATE INDEX idx_logpolicy_correlation ON log_PolicyCapture(correlation_id);
CREATE INDEX idx_logpolicy_timestamp ON log_PolicyCapture(log_timestamp);
CREATE INDEX idx_logpolicy_proxy ON log_PolicyCapture(api_proxy_id);
CREATE INDEX idx_logpolicy_region ON log_PolicyCapture(capture_region);

CREATE INDEX idx_logpolicy_correlation ON log_PolicyCapture(correlation_id);
CREATE INDEX idx_logpolicy_timestamp ON log_PolicyCapture(log_timestamp);
CREATE INDEX idx_logpolicy_proxy ON log_PolicyCapture(api_proxy_id);
CREATE INDEX idx_logpolicy_region ON log_PolicyCapture(capture_region);

CREATE INDEX idx_logpolicy_correlation ON log_PolicyCapture(correlation_id);
CREATE INDEX idx_logpolicy_timestamp ON log_PolicyCapture(log_timestamp);
CREATE INDEX idx_logpolicy_proxy ON log_PolicyCapture(api_proxy_id);
CREATE INDEX idx_logpolicy_region ON log_PolicyCapture(capture_region);

İndeks	Kullanım Amacı
`idx_logpolicy_correlation`	Aynı isteğe ait istek ve yanıt kayıtlarını `correlation_id` üzerinden birleştirme
`idx_logpolicy_timestamp`	Zaman aralığına göre filtreleme ve tarih bazlı raporlama
`idx_logpolicy_proxy`	Belirli bir API Proxy’ye ait kayıtları listeleme
`idx_logpolicy_region`	Pipeline aşamasına göre (`FROM_CLIENT`, `TO_CLIENT` vb.) filtreleme

İstek ve yanıtı aynı satırda görüntülemek için correlation_id üzerinden self-join yapabilir, capture_region alanını ayrım kriteri olarak kullanabilirsiniz. Örneğin:

SELECT req.correlation_id, req.from_client_ro_body AS request_body, res.from_client_ro_body AS response_body
FROM log_PolicyCapture req
JOIN log_PolicyCapture res ON req.correlation_id = res.correlation_id
WHERE req.capture_region = 'FROM_CLIENT' AND res.capture_region = 'TO_CLIENT';

Log tabloları zaman sıralı ve büyük hacimli veri biriktirdiğinden, log_timestamp kolonuna göre günlük partition (bölümleme) uygulanması önerilir. Günlük partition sayesinde eski kayıtların silinmesi DROP PARTITION ile neredeyse anlık gerçekleşir ve tarih aralığı sorguları yalnızca ilgili partition’ları tarar.Partition tanımı veritabanına göre farklılık gösterir:

Oracle: PARTITION BY RANGE (log_timestamp) INTERVAL (NUMTODSINTERVAL(1, 'DAY')) ile otomatik günlük partition oluşturulur.
PostgreSQL: PARTITION BY RANGE (log_timestamp) tanımlanır; her gün için alt tablo oluşturulur (örn. log_PolicyCapture_20260421).
MySQL/MariaDB: PARTITION BY RANGE (TO_DAYS(log_timestamp)) kullanılır. Partition anahtarı birincil anahtarın (PRIMARY KEY) parçası olmalıdır.
SQL Server: Partition function ve partition scheme ile günlük aralık tanımlanır; yeni partition’lar genellikle zamanlanmış bir iş ile eklenir.

MongoDB

MongoDB konnektörü kullanıldığında tablo oluşturma gerekmez. Veriler log_policycapture koleksiyonuna otomatik olarak yazılır.

Gizlilik Ayarları

Loglama politikasında gizlilik aktif edildiğinde, belirtilen alan adlarına sahip başlık, parametre ve gövde verileri maskelenir. Bu özellik KVKK/GDPR gibi veri koruma gereksinimlerini karşılamak için kullanılabilir. Maskeleme işlemi, veriler konnektöre gönderilmeden önce uygulanır. Konnektör seviyesindeki gizlilik ayarları ise bundan bağımsız olarak ayrıca uygulanır.

Politikayı Silme

Bu politikanın silme adımları ve kullanımdayken uygulanacak işlemler için Politika Nedir? sayfasındaki Politikayı Silme bölümüne bakabilirsiniz.

Politikayı Dışa/İçe Aktarma

Bu politikanın dışa aktarma (Export) adımları ve kullanılabilecek seçenekler için Politika Nedir? sayfasındaki Politikayı Dışa/İçe Aktarma bölümüne bakabilirsiniz.

Politikayı API’ye Bağlama

Bu politikanın API’lere nasıl bağlanacağına ilişkin süreç için Politika Yönetimi sayfasındaki Politikayı API’ye Bağlama bölümüne bakabilirsiniz.

API Geliştirme

Yönlendirme

Politikalar

İzleme ve Analiz

Global Ayarlar

Test ve Araçlar

Yükleme ve Sürüm

Genel Bakış

Kullanım Alanları

Desteklenen Hedefler

Çalışma Modu

Yapılandırma Alanları

Veri Yapısı

Örnek JSON Çıktısı

Pipeline Konumu (`cr`) Değerleri

Ekleme Kapsamı (`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

Önerilen İndeksler

MongoDB

Gizlilik Ayarları

Politikayı Silme

Politikayı Dışa/İçe Aktarma

Politikayı API’ye Bağlama

API Geliştirme

Yönlendirme

Politikalar

İzleme ve Analiz

Global Ayarlar

Test ve Araçlar

Yükleme ve Sürüm

​Genel Bakış

​Kullanım Alanları

​Desteklenen Hedefler

​Çalışma Modu

​Yapılandırma Alanları

​Veri Yapısı

​Örnek JSON Çıktısı

​Pipeline Konumu (cr) Değerleri

​Ekleme Kapsamı (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

​Önerilen İndeksler

​MongoDB

​Gizlilik Ayarları

​Politikayı Silme

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

​Politikayı API’ye Bağlama

Genel Bakış

Kullanım Alanları

Desteklenen Hedefler

Çalışma Modu

Yapılandırma Alanları

Veri Yapısı

Örnek JSON Çıktısı

Pipeline Konumu (`cr`) Değerleri

Ekleme Kapsamı (`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

Önerilen İndeksler

MongoDB

Gizlilik Ayarları

Politikayı Silme

Politikayı Dışa/İçe Aktarma

Politikayı API’ye Bağlama