Akışlar

Loglama

Her iki uygulama da (Public API + batch worker) çalışırken ne yaptığını düzenli bir biçimde kaydeder. Bu kayıtlara log denir. Loglar tek bir merkeze — code-agent log toplama ucuna — gönderilir; operatör bunları code-agent panelindeki Logs sekmesinden arayıp görüntüler. Bir sorun yaşandığında "ne oldu, ne zaman oldu, hangi istekte oldu" sorularının cevabı buradadır.

Loglar nereden nereye gider?

Uygulamalar logu Serilog kütüphanesiyle üretir. Serilog'un HTTP sink'i logları toplu (batch) halde — saniyede bir — code-agent log toplama ucuna POST eder. Adres CODE_AGENT_LOG_INGEST_URL ortam değişkeninden gelir (varsayılan http://host.docker.internal:5001/api/logs/ingest). Operatör bu logları ayrı bir arayüz kurmadan doğrudan code-agent panelindeki Logs sekmesinde görür.

api-yos / batch
Serilog · logu üret

→

Serilog HTTP sink
toplu (batch) · ~1sn

→

code-agent log ingest
:5001 · /api/logs/ingest

→

code-agent paneli
Logs sekmesi · görüntüle

Üç tip log (üç ayrı kutu)

Loglar karışmasın diye amaçlarına göre üç ayrı "kutuya" (teknik adıyla index) ayrılır. Her kutu farklı bir soruyu cevaplar. Hangi kutuya bakacağınızı bilmek işi çok hızlandırır:

request

Gelen her HTTP isteğinin özeti: hangi yöntem (GET/POST), hangi yol, dönen durum kodu, ne kadar sürdü ve isteğin/yanıtın gövdesi (hassas alanlar gizlenmiş halde). "Bu istek geldi mi, ne döndü?" sorusu buradadır.

error

Sadece hatalar: hata tipi, kodu, hangi yolda oluştu, ayrıntısı. Bir şey bozulduğunda ilk bakılacak yer burasıdır.

bkmservice

Bankaya (HHS) giden ÖHVPS çağrıları: hangi servis, hangi uç, yöntem, durum, süre ve çağrının istek/yanıt gövdesi (yine hassas alanlar gizlenmiş halde). "Bankayla aramda ne konuşuldu?" sorusu buradadır.

Her kaydın hangi kutuya ait olduğu log_kind alanında (request, error, bkmservice), hangi uygulamadan geldiği ise app alanında durur: apiyos (Public API), apiyosbatch (batch worker). Panelde bu iki alanla filtreleyerek tek görünümde tümünü ayırt edebilirsiniz.

Not: Sağlık kontrolü (health) istekleri loglanmaz — bunlar saniyede bir gelen "ayakta mısın?" yoklamalarıdır ve logu gürültüye boğmamaları için kayıt dışı tutulur.

Bir log kaydı neye benzer?

Loglar temiz ve tutarlı bir düzendedir; gereksiz çerçeve gürültüsü ayıklanır. Aşağıda örnek bir istek (request) kaydı var. password alanının nasıl [REDACTED] ile gizlendiğine dikkat edin:

{
  "@timestamp": "2026-07-08T09:12:03.4Z",
  "app": "apiyos",
  "log_kind": "request",
  "level": "Information",
  "message": "HTTP request",
  "correlation_id": "c9bb2ea093b247abae0a51dbda253394",
  "trace_id": "acee3e0806cbf02bd173459de0ac42ea",
  "http": {
    "method": "POST",
    "path": "/api/v1/auth/register",
    "status": 200,
    "duration_ms": 13.6,
    "request_body": { "userKey": "demo-user-1", "customerNo": "1001" },
    "response_body": { ... }
  }
}

bkmservice kayıtları da benzer yapıdadır ama http yerine bankaya giden çağrının uç noktasını, istek/yanıt gövdesini (yine scrub'lı) ve süresini tutar — böylece bir ödeme veya hesap sorgusunun bankada gerçekten ne kadar sürdüğünü görebilirsiniz.

Güvenlik: hassas veri neden ve nasıl gizlenir?

Uygulama anahtarı, token, kart numarası asla düz metin loglanmaz. Loglar merkeze gitmeden önce bir temizleyiciden (scrub — loglara yazmadan önce anahtar/token gibi hassas veriyi [REDACTED] ile gizleme) geçer. token, secret, key gibi alanlar ile IBAN, TCKN, kart numarası (PAN), CVV gibi kişisel veriler (PII) otomatik olarak [REDACTED] yazısıyla değiştirilir. Bu temizlik JSON gövdelerin içine kadar iner; iç içe alanlar da taranır. Yani birisi logları görse bile gerçek anahtara veya kart bilgisine ulaşamaz.

Aynı isteğin loglarını nasıl bir araya getiririm?

Tek bir istek genelde birden çok log satırı üretir (bir request, belki bir error, belki birkaç bkmservice çağrısı). Bunları birbirine bağlayan iki anahtar alan vardır:

Alan	Ne işe yarar
`correlation_id`	Aynı isteğe ait tüm log satırlarını birbirine bağlayan kimlik. Bir sorunu ararken önce bununla filtreleyin — o isteğe dair her şey tek listede toplanır.
`trace_id` / `span_id`	Dağıtık izleme (OpenTelemetry) kimlikleri. Bir isteğin API'den batch worker'a kadar servisler arası yolculuğunu bağlar. Hata yanıtındaki `traceId` ile aynı isteği ifade eder.
`app`	Logun hangi uygulamadan geldiği: apiyos (Public API), apiyosbatch (batch worker).
`log_kind`	Kayıt türü: request, error veya bkmservice. Hangi kutuya baktığınızı ayırt etmenizi sağlar.

İpucu: Bir kullanıcı hata yaşadıysa, size dönen hata yanıtındaki traceId (ya da log'taki correlation_id) değerini code-agent panelinin Logs sekmesinde aratın; o isteğin baştan sona hikâyesini tek ekranda görürsünüz.

Logları nasıl görüntülerim?

code-agent panelini açın ve api-yos projesinin sayfasına gidin.
Logs sekmesine girin — buraya gelen tüm loglar (api-yos + batch) tek listede toplanır.
Kayıt türüne göre daraltın: log_kind = request (istekler), error (hatalar) veya bkmservice (banka çağrıları); uygulama için app = apiyos / apiyosbatch.
Belirli bir istek için filtre yazın, örneğin correlation_id = c9bb2ea0... veya durum kodu 500. Zaman aralığını daraltarak sonucu netleştirin.