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 |
| ActiveMQ | JMS (ActiveMQ) |
| Logback | Dosya (Logback) |
Ç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. ILM politikası, index template ve data stream kurulum komutları için bakınız: Apinizer Log Tabloları Oluşturma Komutları — Log Politikası.
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 Yönetimi sayfasındaki Akıştan Politika Kaldırma bölümüne bakabilirsiniz.
Politikayı Dışa/İçe Aktarma
Bu politikanın dışa aktarma (Export) ve içe aktarma (Import) adımları için Export/Import sayfasına 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.