Appearance
Gözlemlenebilirlik Tasarımı (Observability Design)
- Sahip: Simetri
- Son Güncelleme: 2026-04-17
- Durum: Kabul edildi (ADR-005). Implementasyon ilk prod deploy öncesinde yapılacak.
- Tetikleyici (dosya güncellemesi): Yeni metrik / log alanı / trace span eklendiğinde; alerting eşiği değiştiğinde; observability stack değişikliğinde.
1. Neden Gerekli?
İki regülatif bağlayıcılık + bir operasyonel gereklilik:
- EU AI Act Art. 61 — Yüksek riskli AI sistemlerinin prod sonrası davranışı sürekli izlenmeli.
- NIST AI RMF MEASURE 4.1 — "Post-deployment monitoring" fonksiyonu.
- Operasyonel ihtiyaç — Model davranış bozulması (drift), latency spike, RLS ihlal denemesi gibi olaylar sessizce geçmemeli.
Audit trail (audit-trail.md) compliance denetimi içindir — immutable, append-only, uzun süreli saklama. Observability ise operasyonel farkındalık içindir — kısa retention, hızlı sorgulama, anlık alarm.
İkisi birbirini tamamlar, ikame etmez.
2. Stack ve Veri Akışı
Karar: OpenTelemetry (instrumentation) + Grafana Cloud Free (backend). Detay ve gerekçe: guides/architecture-decisions/005-observability-stack-selection.md.
┌─────────────────────────────────────────────────────────────────┐
│ Railway Pro (compute) │
│ │
│ ┌──────────────┐ ┌──────────────────────┐ │
│ │ api-gateway │ │ psychometric-engine │ │
│ │ (NestJS) │ │ (FastAPI) │ │
│ │ │ │ │ │
│ │ OTLP SDK ─────┼────┼── OTLP SDK ─────────┼──► Grafana Cloud │
│ │ │ │ │ ┌────────────┐│
│ │ stdout/stderr─┼────┼── stdout/stderr ─────┼──► │ Loki (log) ││
│ └──────────────┘ └──────────────────────┘ │ Mimir (met)││
│ │ Tempo (trc)││
│ Railway Dashboard ← infra metrics (CPU/RAM/Net) └────────────┘│
└─────────────────────────────────────────────────────────────────┘OTLP transport: HTTPS (gRPC yerine — Railway'de outbound gRPC'de port kısıtı olabilir).
Collector (opsiyonel): MVP'de SDK'lar doğrudan Grafana Cloud'a gönderir. Trafik arttığında veya PII redaction merkezi olacaksa OpenTelemetry Collector ayrı Railway servisine eklenir.
3. Metrik Taksonomisi
3.1. Sistem Sağlığı (Infrastructure + Application)
| Metrik | Tip | Birim | Alarm eşiği |
|---|---|---|---|
http_request_duration_seconds | Histogram | saniye | p99 > 2s → warn; p99 > 5s → critical |
http_requests_total | Counter | — | — (trend için) |
http_error_rate | Gauge (5dk pencere) | % | > %5 → warn; > %15 → critical |
db_query_duration_seconds | Histogram | saniye | p99 > 1s → warn |
db_connection_pool_usage | Gauge | % | > %80 → warn |
redis_queue_depth | Gauge | adet | > 1000 → warn |
Railway infra metrikleri (CPU / RAM / disk) Railway Dashboard'dan izlenir. Duplike edilmez.
3.2. Model Davranışı (AI / LLM — EU AI Act Art. 61 Odağı)
| Metrik | Tip | Birim | Alarm eşiği | Kaynak |
|---|---|---|---|---|
llm_direction_accuracy | Gauge (günlük eval) | % | < %85 → critical | Golden dataset eval |
llm_hallucination_rate | Gauge (günlük eval) | % | > %2 → critical | Golden dataset eval |
llm_eval_drift | Gauge (7-gün hareketli ort. farkı) | % | delta | |
llm_token_usage_total | Counter | token | — (maliyet için) | LLM Orchestrator |
llm_cost_per_request | Histogram | USD | > $0.50 → warn | LLM Orchestrator |
llm_latency_seconds | Histogram | saniye | p99 > 10s → warn | LLM Orchestrator |
adversarial_rejection_rate | Gauge (CI eval) | % | < %95 → critical | adversarial-eval-suite |
3.3. Güvenlik ve Uyum
| Metrik | Tip | Alarm eşiği |
|---|---|---|
rls_violation_attempts | Counter | > 0 → critical (anlık) |
pii_redaction_events | Counter | — (trend izleme; azalma = pipeline bozuk?) |
auth_failure_rate | Gauge (5dk) | > %20 → critical |
audit_write_failures | Counter | > 0 → critical (audit trail yazılamıyorsa log kaybı) |
consent_level_downgrades | Counter | — (kullanıcı izin kısıtlamaları; trend takibi) |
3.4. İş Metrikleri (Opsiyonel — Dashboards)
| Metrik | Açıklama |
|---|---|
active_sessions | Anlık aktif sohbet oturumu |
context_room_distribution | PRO / SOCIAL / DISCOVERY oda dağılımı |
label_override_rate | Kullanıcı müdahale oranı (veri tutarlılığı göstergesi) |
4. Log Hiyerarşisi
4.1. Format: Structured JSON
Tüm log çıktısı JSON lines formatında stdout'a yazılır. Railway + Grafana Loki ikisi de bu formatı native parse eder.
json
{
"timestamp": "2026-04-17T10:30:00.123Z",
"level": "INFO",
"service": "psychometric-engine",
"trace_id": "abc123def456",
"span_id": "789ghi",
"context_room_id": "cr_42",
"message": "Scoring completed",
"duration_ms": 145,
"trait": "bigfive_openness",
"shift": 1.2
}4.2. Severity Seviyeleri
| Level | Ne zaman | Alarm? |
|---|---|---|
ERROR | İstek başarısız; kullanıcı etkilendi | Hata oranı eşiğinde evet |
WARN | Kötüleşme sinyali; henüz hata yok | Eşik aşımında evet |
INFO | Normal akış log'u (request start/end, scoring completed) | Hayır |
DEBUG | Geliştirme ortamı detayı | Prod'da kapalı (volume + PII riski) |
4.3. PII Redaction Pipeline
Kritik: Log ve trace'ler kullanıcı metin parçaları içerebilir → PII sızıntısı riski (threat-model.md §3.5).
Redaction katmanları (defense in depth):
- Uygulama seviyesi — Logger wrapper, bilinen PII alanlarını (
user_text,transcript_snippet) hash'ler veya maskeler (***). İlk ve en önemli hat. - Collector seviyesi (ileride) — OpenTelemetry Collector'da
transformprocessor ile regex-based PII pattern sweep (email, TC kimlik, telefon). - Grafana Cloud seviyesi — Loki'de label filter;
user_textlabel'ı asla Loki'ye gönderilmez.
Kural: Hiçbir log satırında ham kullanıcı metni olmamalı. vector-privacy.md sanitization pipeline'ı log katmanına da uygulanır.
5. Trace Modeli (Distributed Tracing)
5.1. Trace Context Propagation
Her HTTP request için OpenTelemetry trace context (W3C Trace Context header: traceparent) oluşturulur.
[B2C Mobile] → [api-gateway] → [Redis queue] → [psychometric-engine]
│ │ │
│ span: gateway (async) span: scoring
│ ├─ auth ├─ sanitize
│ ├─ consent-check ├─ llm-inference
│ └─ route ├─ ema-calculate
│ └─ vectorize
│
trace_id: abc123 (tüm span'ler aynı trace altında)5.2. Trace ID Korelasyonu
| ID | Nerede üretilir | Nerede kullanılır |
|---|---|---|
trace_id | OpenTelemetry SDK (gateway giriş noktası) | Tüm span'ler, tüm log satırları |
context_room_id | Auth middleware (JWT'den) | Log + span attribute |
audit_event_id | Audit trail yazarken | Span attribute → Grafana'da trace → audit event korelasyonu |
Bu üçlü sayesinde bir Grafana sorgusu: trace_id → audit_event_id → immutable log kaydı zinciri kurulabilir. Denetçi için "hangi request hangi audit event'i tetikledi?" sorusu yanıtlanır.
6. Alerting ve Incident Bağlantısı
6.1. Alert Routing
| Alarm Severity | Aksiyon | İlişkili incident sınıfı (incident-response.md §1) |
|---|---|---|
| Critical | Slack #humindx-incident + PagerDuty/email | S1-S5 (veri ihlali, RLS bypass, availability) |
| Warning | Slack #humindx-ops | — (henüz incident değil, izle) |
| Info | Dashboard'da görünür, bildirim yok | — |
6.2. Pre-configured Alert Rules (MVP)
llm_direction_accuracy < 85→ critical → S6 (Model Behavior Regression)rls_violation_attempts > 0→ critical → S2 (RLS Bypass)http_error_rate > 15%(5dk pencere) → critical → S5 (Availability)audit_write_failures > 0→ critical → log kaybı riski, S1'e eşdeğerllm_eval_drift |delta| > 5→ warning → S6 ön uyarıhttp_request_duration_seconds p99 > 5s→ critical → S5
Alert kuralları Grafana Cloud Alerting'de tanımlanır. Notification channel: Slack webhook + email.
7. Dashboard Tasarımı (Özet)
| Dashboard | İçerik | Birincil izleyici |
|---|---|---|
| System Health | Latency histogramları, error rate, throughput, DB connection pool, Redis queue | On-call / SRE |
| Model Behavior | Direction Accuracy trend, hallucination rate, eval drift, token cost | AI/ML mühendis |
| Security | RLS violation attempts, PII redaction events, auth failure rate, audit write health | Security lead |
| Business (opsiyonel) | Active sessions, context room distribution, label override rate | Product |
Dashboard JSON template'leri infra/grafana/dashboards/ altında version-control'da tutulur (ileride).
8. Retention ve Veri Sınıflandırması
| Veri tipi | Retention | Nerede | Compliance notu |
|---|---|---|---|
| Audit trail (immutable) | Süresiz (veya GDPR DSAR'a kadar) | PostgreSQL / Immutable Log Store | Compliance kaydı — audit-trail.md |
| Operational metrics | 14 gün (Grafana Cloud Free) | Grafana Mimir | Operasyonel; compliance dışı |
| Operational logs | 14 gün | Grafana Loki | PII redacted; operasyonel |
| Traces | 14 gün | Grafana Tempo | PII redacted; operasyonel |
14 gün yeterli mi? Evet — compliance için uzun süreli kayıt audit-trail.md ile sağlanır. Observability verileri "son 2 hafta ne oldu?" sorusunu yanıtlar. Retention artışı gerekirse Grafana Cloud Pro'ya geçiş yeterli.
9. Implementasyon Fazları
| Faz | Ne yapılır | Tetikleyici |
|---|---|---|
| Faz 0 (bu doküman) | Tasarım + ADR-005 kabul | SIM-177 (şimdi) |
| Faz 1 | OTLP SDK entegrasyonu (api-gateway + psychometric-engine), stdout JSON logging, temel metrikler | İlk endpoint'ler prod'a hazır olunca |
| Faz 2 | Grafana Cloud hesap açma, dashboard + alert rule kurulumu, Slack webhook | Faz 1 ile paralel |
| Faz 3 | Model behavior metrikleri (golden dataset eval → metrik emit), eval drift alerting | Golden dataset eval CI pipeline çalışır olunca |
| Faz 4 (opsiyonel) | OpenTelemetry Collector (merkezi PII redaction + batching), Railway log drain → Loki | Trafik artarsa veya collector-seviye redaction gerekirse |
10. Referanslar
- ADR-005:
guides/architecture-decisions/005-observability-stack-selection.md - Audit trail (compliance logging):
security/audit-trail.md - PII redaction:
security/vector-privacy.md,security/threat-model.md§3.5 - Incident response:
guides/incident-response.md— §2.1 alarm kaynakları bu dosyaya linkler - EU AI Act Art. 61:
security/eu-ai-act-compliance.md§6 - NIST AI RMF MEASURE 4.1:
security/nist-ai-rmf-mapping.md - Adversarial eval eşikleri:
security/adversarial-eval-suite.md§7
Son Güncelleme: 2026-04-17 — İlk sürüm, SIM-177. Stack: OpenTelemetry + Grafana Cloud Free (ADR-005).