git:20260704.12791fe to git:20260707.abd2d2b

36 added, 36 removed. Audit A to A.

---

name: observability

description: |

- Yığın-bağımsız gözlemlenebilirlik: yapılandırılmış log, korelasyon-id, metrik ve trace ekler;

- log'da PII/secret sızıntısını engeller. Üretim sorununu "neden oldu" diye izlenebilir kılar.

- Trigger phrases: "observability", "gözlemlenebilirlik", "yapılandırılmış log", "structured logging", "trace ekle", "metrik ekle", "korelasyon id", "log ekle"

+ Stack-agnostic observability: adds structured logs, correlation ids, metrics, and traces;

+ prevents PII/secret leakage in logs. Makes a production issue traceable to "why it happened".

+ Trigger phrases: "observability", "structured logging", "structured log", "add a trace", "add a metric", "correlation id", "add logging"

---

- # Gözlemlenebilirlik

+ # Observability

- Amaç: bir üretim olayında "ne oldu, nerede, neden" sorusunu **log'a bakarak** yanıtlayabilmek.

- Yığın-bağımsızdır; framework'e özel kütüphane/format için gerektiğinde web araması yap.

+ Goal: to be able to answer "what happened, where, why" during a production incident **by looking at the logs**.

+ It is stack-agnostic; when you need a framework-specific library/format, do a web search.

- ## Üç sinyal

- - **Log** — olay kaydı (yapılandırılmış/JSON, seviyeli).

- - **Metrik** — sayısal zaman serisi (istek sayısı, gecikme, hata oranı, kaynak).

- - **Trace** — bir isteğin servisler arası yolculuğu (span'ler + korelasyon-id).

+ ## Three signals

+ - **Log** — event record (structured/JSON, leveled).

+ - **Metric** — numeric time series (request count, latency, error rate, resource usage).

+ - **Trace** — a request's journey across services (spans + correlation id).

- ## Kontrol listesi

- - [ ] Log **yapılandırılmış** (JSON/anahtar-değer), string interpolation değil

- - [ ] Her log satırında **korelasyon-id** (request/trace id) var

- - [ ] Seviyeler doğru: DEBUG/INFO/WARN/ERROR ayrımı anlamlı

- - [ ] **PII/secret loglanmıyor** (parola, token, kart, TC/kimlik, e-posta gövdesi)

- - [ ] Hata log'u bağlam taşıyor (girdi özeti, kullanıcı/kaynak id — PII değil), stack trace kullanıcıya sızmaz

- - [ ] Kritik iş metriği + altyapı metriği yayılıyor (varsa)

- - [ ] Servisler arası çağrıda korelasyon-id **taşınıyor** (header/propagation)

+ ## Checklist

+ - [ ] Logs are **structured** (JSON/key-value), not string interpolation

+ - [ ] Every log line carries a **correlation id** (request/trace id)

+ - [ ] Levels are correct: the DEBUG/INFO/WARN/ERROR distinction is meaningful

+ - [ ] **No PII/secret is logged** (password, token, card, national/ID number, email body)

+ - [ ] Error logs carry context (input summary, user/resource id — not PII); the stack trace does not leak to the user

+ - [ ] Critical business metric + infrastructure metric are emitted (where applicable)

+ - [ ] The correlation id is **propagated** across service-to-service calls (header/propagation)

- ## Nasıl

- 1. **Yapılandırılmış logger** kur/kullan — çıktı makine-okunur (JSON). Framework'ün önerdiği kütüphaneyi ara.

- 2. **Korelasyon-id**: girişte (HTTP middleware / mesaj tüketici) üret ya da gelen `X-Request-Id`/trace header'ından al; log context'ine koy; alt çağrılara **ilet**.

- 3. **Seviye disiplini**: INFO = iş olayı, WARN = beklenen-ama-dikkat, ERROR = müdahale gerek. DEBUG üretimde kapalı/örneklemeli.

- 4. **Bağlam alanları**: `event`, `correlation_id`, `user_id`(PII değil, opak id), `duration_ms`, `outcome`. Serbest metne gömme.

- 5. **Metrik**: en az RED (Rate, Errors, Duration) veya USE; iş-kritik sayaçlar. Framework metrik kütüphanesini ara.

- 6. **Trace** (dağıtık sistemde): span başlat/bitir, korelasyon-id'yi trace-id'ye bağla.

+ ## How

+ 1. **Structured logger** — set up/use one whose output is machine-readable (JSON). Search for the library the framework recommends.

+ 2. **Correlation id**: generate it at the entry point (HTTP middleware / message consumer) or take it from the incoming `X-Request-Id`/trace header; put it in the log context; **propagate** it to downstream calls.

+ 3. **Level discipline**: INFO = business event, WARN = expected-but-noteworthy, ERROR = needs intervention. DEBUG is off/sampled in production.

+ 4. **Context fields**: `event`, `correlation_id`, `user_id` (not PII, an opaque id), `duration_ms`, `outcome`. Do not embed them in free text.

+ 5. **Metrics**: at minimum RED (Rate, Errors, Duration) or USE; plus business-critical counters. Search for the framework's metrics library.

+ 6. **Trace** (in a distributed system): start/end spans, bind the correlation id to the trace id.

- ## PII / secret sızıntısı (kritik)

- Log'a **asla**: parola, token, API anahtarı, kart no, TC/kimlik, tam e-posta/telefon gövdesi, ham istek gövdesi.

- - Maskele: `user@***`, kart `**** 1234`, token `sk-p…789`.

- - Gerekliyse **opak id** logla (hash/uuid), ham değeri değil.

- - Bu eksen `security-scan` (loglarda hassas veri) ve `privacy-compliance` (KVKK/GDPR) ile örtüşür — kişisel veri varsa onları da tetikle.

+ ## PII / secret leakage (critical)

+ **Never** to the log: password, token, API key, card number, national/ID number, full email/phone body, raw request body.

+ - Mask: `user@***`, card `**** 1234`, token `sk-p…789`.

+ - When needed, log an **opaque id** (hash/uuid), not the raw value.

+ - This axis overlaps with `security-scan` (sensitive data in logs) and `privacy-compliance` (KVKK/GDPR) — if personal data is involved, trigger those too.

- ## Değişmez kurallar

- 1. **Yapılandırılmış > serbest metin** — grep'lenebilir, ayrıştırılabilir.

- 2. **Korelasyon-id her satırda** — yoksa dağıtık hata izlenemez.

- 3. **PII/secret loglanmaz** — maskele veya opak id.

- 4. **Gürültü yapma** — her satır bir soruyu yanıtlamalı; anlamsız spam log ekleme.

- 5. **Mevcut format'a uy** — repoda logger varsa onun kalıbını sürdür, yenisini dayatma.

+ ## Invariant rules

+ 1. **Structured > free text** — greppable, parseable.

+ 2. **Correlation id on every line** — without it, a distributed error is untraceable.

+ 3. **No PII/secret is logged** — mask it or use an opaque id.

+ 4. **Do not make noise** — every line must answer a question; do not add meaningless spam logs.

+ 5. **Match the existing format** — if the repo has a logger, follow its pattern; do not impose a new one.