Observer Servisi

Observer Servisi, Cınga Kafka hattını read-only izleyen ve pipeline performansını ölçen gözlem katmanıdır.

Bu servis iş kuralı çalıştırmaz, veri dönüştürmez, downstream’i tetiklemez. Yalnızca event akışından metrik üretir ve yavaş/hatalı noktaları görünür hale getirir.

Sorumluluk

• Cınga topic’lerini bağımsız consumer group ile dinlemek
• Servis bazlı işlem sürelerini ölçmek (process_ms, stage latency)
• Topic lag, retry, fail oranlarını çıkarmak
• p50/p95/p99 gecikme metriklerini üretmek
• Heartbeat eventlerinden cihaz canlılık dağılımını çıkarmak (online/degraded/offline)
• Alarm eşiklerini değerlendirmek (SLO ihlali)

Dinlenen Topicler

• cinga.ingest.raw
• cinga.stream.assembled
• cinga.calibration.ready
• cinga.raw.persisted
• cinga.synth.ready
• cinga.window.ready
• cinga.heartbeat.metrics
• cinga.heartbeat.status
• cinga.heartbeat.failed
• cinga.ingest.failed
• cinga.stream.failed
• cinga.calibration.failed
• cinga.raw.failed
• cinga.synth.failed
• cinga.window.failed
• cinga.dlq.*

Not: Kafka client pattern-subscribe destekliyorsa cinga.*.failed pattern’i kullanılabilir; destek yoksa yukarıdaki explicit liste zorunludur.

Consumer Group ve İzolasyon

Observer yalnız kendi consumer group’u ile çalışır:

• cg.cinga.observer

Kurallar:

• Ana işleyen consumer group’larla paylaşılmaz.
• Offset yönetimi yalnız gözlem amaçlıdır.
• Observer iş pipeline topic’lerine (cinga.*.ready, cinga.*.failed) produce etmez.
• Observer yalnız bildirim/webhook kanallarına ve metrik depolarına çıktı üretir.

Event Ölçüm Sözleşmesi

Observer’ın doğru ölçüm yapabilmesi için event payload’larında observer alanları tek bir obje altında taşınmalıdır:

{
  "event": "synth.ready.v1",
  "meta": {
    "schema_version": 1,
    "trace_id": "9f3f...",
    "producer_service": "synth-service",
    "produced_at": "2026-03-11T15:22:10.121Z",
    "process_ms": 18
  },
  "context": {
    "device_id": "400000011D081B70",
    "stream_id": 9823412
  },
  "error": null
}

Opsiyonel observer türevi alanlar:

• consumed_at
• stage_latency_ms
• end_to_end_ms

Hesap tanımları:

• stage_latency_ms = consumed_at - produced_at
• end_to_end_ms = produced_at(window.ready.v1) - produced_at(ingest.received.v1)

Ölçülen Metrikler

• Stage latency (produce -> consume)
• Service process time (process_ms)
• Topic consumer lag
• Retry count
• Failed event rate
• DLQ rate
• End-to-end latency (ingest.received.v1 -> window.ready.v1)

Alarm Eşikleri (Öneri)

• p95 stage_latency_ms > 1500 ms -> high
• p95 stage_latency_ms > 3000 ms -> critical
• topic_lag > 5000 mesaj -> high
• topic_lag > 10000 mesaj -> critical
• failed_rate > %1 -> high
• failed_rate > %3 -> critical
• dlq_rate > %0.1 -> high
• dlq_rate > %0.5 -> critical

Eşikler ortam bazında (dev/stage/prod) ayrı tutulmalıdır. Alarm fırtınasını azaltmak için ihlal en az N=3 ardışık ölçüm penceresinde doğrulanmalıdır.

Bildirim Kanalları (Telegram / WhatsApp / vb.)

Observer bir sorun tespit ettiğinde yalnız dashboard'a yazmakla kalmamalı, aktif bildirim de üretmelidir.

Önerilen kanal hiyerarşisi:

1. Telegram (birincil, hızlı operasyon kanalı)
2. WhatsApp (yedek / kritik eskalasyon)
3. E-posta (özet rapor)

Önerilen bildirim payload'ı:

{
  "alert_id": "obs-20260312-00192",
  "severity": "high",
  "service": "synth-service",
  "topic": "cinga.synth.ready",
  "metric": "p95_stage_latency_ms",
  "value": 2410,
  "threshold": 1500,
  "window": "5m",
  "trace_id": "9f3f...",
  "stream_id": 9823412,
  "detected_at": "2026-03-12T19:04:12Z"
}

Bildirim kuralları:

• Aynı alarm için dedup_key kullanılmalı (alarm fırtınasını engellemek için)
• cooldown süresi tanımlanmalı (örn. 10 dk)
• severity=critical için Telegram + WhatsApp birlikte gönderilmeli
• Alarm kapandığında resolved bildirimi de gönderilmeli

Redis Metric State (UI için)

Observer, UI tarafında hızlı görüntüleme için metriklerin özetini Redis'te tutmalıdır.

Önerilen key yapısı:

• observer:service:{service_name}:metrics:latest
• observer:topic:{topic_name}:metrics:latest
• observer:pipeline:global:metrics:latest

Örnek Redis gövdesi:

{
  "service": "synth-service",
  "window": "5m",
  "throughput_eps": 182.4,
  "p50_stage_latency_ms": 120,
  "p95_stage_latency_ms": 680,
  "p99_stage_latency_ms": 1500,
  "consumer_lag": 412,
  "failed_rate_pct": 0.4,
  "dlq_rate_pct": 0.02,
  "updated_at": "2026-03-12T19:06:30Z"
}

Redis retention önerisi:

• latest keyleri: 24 saat TTL
• zaman serisi detayları (opsiyonel): 7 gün TTL
• uzun dönem trend: TSDB/Grafana backend (Redis yalnız hızlı UI cache)

Metrics Emit ve Retention Politikası

• Emit interval: 10s
• Alert evaluate window: 1m ve 5m
• Raw metric retention: 7 gün
• Downsample retention (p95/p99): 90 gün

Akış Diyagramı

İşletim Notları

• Observer servisinin gecikmesi ana pipeline’ı etkilemez.
• Metrics yazımı batch yapılmalıdır (yüksek topic hacminde).
• observer.trace_id + stream_id korelasyonu zorunlu tutulmalıdır.
• Tüm node’larda NTP/saat senkronu zorunludur; aksi halde latency metrikleri yanıltıcı olur.

Servis Bazlı SLO Hedefleri (Öneri)

Metrik	Hedef
p95 stage_latency_ms	< 1500ms
topic_lag	< 5000
failed_rate	< 1%
dlq_rate	< 0.1%

Çıktı

Observer Servisi çıktısı:

• Pipeline performans metrikleri
• SLO/SLA ihlal alarmı
• Yavaş/hatalı stage görünürlüğü