Kafka Topic Standard

Bu doküman, Qapu servislerinde Kafka topic yapısını servis bazlı ve operasyonel olarak yönetilebilir bir standarda bağlar.

Kapsam

• Bu sayfa, topic adlandırma ve sahiplik standardının tek kaynak referansıdır.
• Event payload şeması, servis bazlı event-contracts dokümanlarında tanımlanır.
• Servisler arası tüm yeni topic kararlarında bu standart zorunludur.

Hedef

• Topic sayısını kontrol altında tutmak
• Event semantiğini topic adından ayırarak sürdürülebilir gelişim sağlamak
• Producer/consumer sözleşmesini servisler arası tutarlı hale getirmek

Temel Model

Her servis için varsayılan model:

1. Bir ana event topic'i
2. Bir servis DLQ topic'i

Örnek:

• Ana topic: qapu.<service>
• DLQ topic: qapu.dlq.<service>

Servis Topic Formatı

Bu proje için standart format qapu.<service> olarak sabitlenmiştir.

• Doğru: qapu.ingest, qapu.stream, qapu.egress
• Yanlış: qapu.ingest.events, ingest, qapu.ingest.v1

Not: <service> yalnız kullanımı (prefix'siz) bu projede standart dışıdır. Tüm ortamlarda qapu. prefix'i zorunludur.

Topic ve Event Ayrımı

• Topic: taşıma kanalı ve operasyonel sınır
• Event: payload semantiği ve versiyonlu sözleşme

Aynı topic içinde birden fazla event taşınabilir:

• egress.sent.v1
• egress.failed.v1

Event ayrımı payload içindeki event alanıyla yapılır.

Adlandırma Kuralları

• Küçük harf ve nokta ayraç: qapu.<service>
• Ortak prefix zorunlu: qapu.
• Servis adı tekil ve stabil olmalı: ingest, stream, egress, automation
• DLQ topic adlandırması sabit: qapu.dlq.<service>
• Regex: ^qapu\.[a-z0-9-]+$ (servis topic)
• Regex: ^qapu\.dlq\.[a-z0-9-]+$ (servis DLQ)

Ortak İletişim Topicleri

Servis topiclerinden ayrık, platform genelinde kullanılabilecek ortak topicler aşağıdadır.

Topic	Kullanım Amacı	Producer Sınırı	Consumer Örneği
qapu.system.audit	Sistem seviyesi denetim/audit olayları	Tüm servisler (audit olayı)	Audit/Compliance
qapu.system.alerts	Operasyonel alarm ve kritik durum yayını	Observer, Egress, Automation	NOC, Alerting worker
qapu.integration.events	Servisler arası genel entegrasyon olayları	Entegrasyon odaklı servisler	API Gateway, Integration worker
qapu.log.error	Merkezi hata log akış topic'i	Tüm servisler (yalnız hata log)	SIEM, Log pipeline, Ops dashboard
qapu.log.event	Merkezi operasyonel event log topic'i (opsiyonel)	Tüm servisler (seçili event özetleri)	BI, Audit analytics, Ops dashboard

Kurallar:

• Ortak topic açma kararı architecture review onayı gerektirir.
• Ortak topic, servis topic'inin yerine geçmez; tamamlayıcı katmandır.
• Ortak topic'te event türü mutlaka payload event alanından ayrışmalıdır.

DLQ ve Log Hibrit Politikası

Bu standartta DLQ ve log amaçları ayrık tutulur:

• DLQ: replay ve hata izolasyonu için servis bazlı tutulur (qapu.dlq.<service>).
• Log topic: merkezi gözlem ve raporlama için kullanılır (qapu.log.error, opsiyonel qapu.log.event).

Kurallar:

• DLQ mesajları dağıtılmaz veya tek bir merkezi DLQ'da birleştirilmez.
• Her kalıcı hata durumunda, servis kendi DLQ topic'ine yazarken aynı zamanda qapu.log.error topic'ine özet log yayını yapabilir.
• qapu.log.error replay kaynağı değildir; operasyonel görünürlük kaynağıdır.
• qapu.log.event yalnız seçili olay özetleri içindir; tüm eventlerin aynalanması zorunlu değildir.

qapu.log.error için önerilen minimum alanlar:

• source_service
• source_topic
• event
• trace_id
• failed_stage
• error_code
• retryable
• replay_target
• first_failed_at
• last_failed_at

Ne Zaman Ek Topic Açılır?

Varsayılan dışında ek topic açmak için en az bir güçlü gerekçe olmalıdır:

• Farklı retention zorunluluğu
• Farklı ACL / güvenlik sınırı
• Farklı partition key ihtiyacı
• Çok yüksek hacim nedeniyle bağımsız ölçek ihtiyacı

Bu koşullar yoksa yeni topic açılmaz; mevcut servis topic'i kullanılır.

Sahiplik ve Yazma Yetkisi

• Her servis kendi ana topic'inin birincil producer'ıdır.
• Başka bir servis, diğer servisin ana topic'ine yalnız onaylı entegrasyon durumunda yazar.
• DLQ topic'lerine doğrudan iş kodu yazmaz; retry/worker katmanı yazar.

Partition Key ve Sıralama

• Varsayılan partition key: device_id
• Aynı device_id eventleri aynı partition'da kalmalı
• Partition key değişikliği bir şema değişikliği değil, operasyonel uyumluluk değişikliğidir; rollout planı gerektirir.

Consumer Group Kuralı

• Group adları servis bazlı olmalıdır: cg.qapu.<service>
• Bir servis içinde farklı iş rollerine ayrılacaksa suffix kullanılır:
  • cg.qapu.egress.dispatch
  • cg.qapu.egress.observer

Consumer Lag ve Backpressure

Consumer lag, bir topic'teki son yazılan offset ile consumer'ın okuduğu offset arasındaki farktır. Yüksek lag, consumer'ın producer'a yetişemediğini gösterir.

Tespit ve müdahale:

• Her consumer group için lag izlemesi zorunludur; cg.qapu.<service> bazında metrik toplanmalıdır.
• Lag eşiği aşıldığında önce consumer ölçeği artırılmalı; topic partition sayısı artırmak ikinci adımdır.
• Partition sayısı artırmak consumer group yeniden atamaya (rebalance) neden olur; planlı yapılmalıdır.
• Backpressure durumunda producer'da throttle mekanizması devreye alınabilir; ancak bu servis SLO'sunu etkiler ve architecture review gerektirir.
• DLQ lag'i ayrıca izlenmelidir; DLQ'da birikim replay baskısına işaret eder.

Retention ve Replay

Kafka'da bireysel event silinemez; retention politikası topic seviyesinde tanımlanır ve süre dolunca Kafka otomatik temizler.

Varsayılan retention süreleri:

Topic Tipi	Örnek	Varsayılan Retention	Açıklama
Ana servis topic	qapu.<service>	7 gün	Normal tüketim için yeterli; consumer'lar genellikle anlık izler
DLQ topic	qapu.dlq.<service>	30 gün	Manuel replay penceresi; ana topic'ten uzun olmalı
Log error topic	qapu.log.error	14 gün	Ops analizi ve olay korelasyonu için orta süre
Log event topic	qapu.log.event	7 gün	Operasyonel özet; uzun süre tutulması gerekmez
Shared/platform topic	qapu.system.alerts vb.	Servise göre	Her ortak topic için ayrı değerlendirilir

Kurallar:

• DLQ retention süresi her zaman ilgili ana topic retention süresinden uzun olmalıdır.
• Retention süresi değiştirmek operasyonel bir değişikliktir; rollout planı ve consumer onayı gerektirir.
• Replay sadece yetkili operasyon akışıyla yapılmalıdır; consumer offset manuel geri alınmamalıdır.

Compact Topic Politikası

Kafka'da log.cleanup.policy=compact yapılandırması, aynı key'e sahip eski mesajları silerek yalnız en son değeri tutar. Bu özellik Qapu servis topiclerinde varsayılan olarak kullanılmaz.

Kullanım koşulları:

• Yalnız belirli bir key için "son durum" yeterli olduğunda ve geçmiş olayların önemi olmadığında açılabilir.
• Örnek uygun alan: cihaz konfigürasyon snapshot'ı (config.device.<device_id> gibi ayrı bir topic'te).
• Servis ana topic'lerinde (qapu.<service>) compact politikası uygulanmaz; olay geçmişi korunmalıdır.
• Compact topic açma kararı architecture review onayı gerektirir.

Event Envelope Zorunlu Alanları

Her event şu çekirdek alanları taşımalıdır:

• event
• meta.schema_version
• meta.trace_id
• meta.producer_service
• meta.produced_at
• context.device_id (cihaz bağlamlı akışlarda)

Kısa Karar Matrisi

Soru	Karar
Yeni servis başlıyor, kaç topic?	qapu.<service> + qapu.dlq.<service>
Farklı event tipi var, yeni topic gerekir mi?	Hayır, önce aynı servis topic'inde taşınmalı
Ne zaman bölünür?	Retention/ACL/partition key/hacim farkı varsa
Prefix'siz <service> topic kullanılsın mı?	Hayır, standart dışı

Topic Envanteri

Aşağıdaki tablo, bu standart kapsamında kullanılan tüm topic'leri tek listede toplar.

Topic	Tip	Sahip	Kullanım
qapu.ingest	Service	Ingest	Ingest servis eventleri
qapu.stream	Service	Stream	Stream servis eventleri
qapu.calibration	Service	Calibration	Kalibrasyon servis eventleri
qapu.raw-writer	Service	Raw Writer	Ham yazım servis eventleri
qapu.synthesis	Service	Synthesis	Sentez servis eventleri
qapu.window	Service	Window	Window servis eventleri
qapu.rule	Service	Rule	Kural değerlendirme eventleri
qapu.action	Service	Action	Aksiyon icra eventleri
qapu.communication	Service	Communication	Cihaz komut iletişim eventleri
qapu.automation	Service	Automation	Otomasyon scheduler eventleri
qapu.egress	Service	Egress	Dış sistem aktarım eventleri
qapu.heartbeat	Service	Heartbeat	Canlılık izleme eventleri
qapu.observer	Service	Observer	Gözlem/ölçüm eventleri
qapu.ledger	Service	Ledger	Denetim zinciri eventleri
qapu.dlq.ingest	DLQ	Retry/Worker	Ingest kalıcı hata kuyruğu
qapu.dlq.stream	DLQ	Retry/Worker	Stream kalıcı hata kuyruğu
qapu.dlq.calibration	DLQ	Retry/Worker	Calibration kalıcı hata kuyruğu
qapu.dlq.raw-writer	DLQ	Retry/Worker	Raw Writer kalıcı hata kuyruğu
qapu.dlq.synthesis	DLQ	Retry/Worker	Synthesis kalıcı hata kuyruğu
qapu.dlq.window	DLQ	Retry/Worker	Window kalıcı hata kuyruğu
qapu.dlq.rule	DLQ	Retry/Worker	Rule kalıcı hata kuyruğu
qapu.dlq.action	DLQ	Retry/Worker	Action kalıcı hata kuyruğu
qapu.dlq.communication	DLQ	Retry/Worker	Communication kalıcı hata kuyruğu
qapu.dlq.automation	DLQ	Retry/Worker	Automation kalıcı hata kuyruğu
qapu.dlq.egress	DLQ	Retry/Worker	Egress kalıcı hata kuyruğu
qapu.dlq.heartbeat	DLQ	Retry/Worker	Heartbeat kalıcı hata kuyruğu
qapu.dlq.observer	DLQ	Retry/Worker	Observer kalıcı hata kuyruğu
qapu.dlq.ledger	DLQ	Retry/Worker	Ledger kalıcı hata kuyruğu
qapu.system.audit	Shared	Platform	Sistem denetim olayları
qapu.system.alerts	Shared	Platform	Operasyonel alarm olayları
qapu.integration.events	Shared	Integration	Servisler arası entegrasyon olayları
qapu.log.error	Shared	Platform	Merkezi hata log akış topic'i
qapu.log.event	Shared	Platform	Merkezi operasyonel event log topic'i (opsiyonel)

Not: Yeni topic eklenirse bu envanter tablosu aynı PR içinde güncellenmelidir.

Uygulama Notu

Bu standart önce Egress servisinde sade modelle test edilmiştir. Diğer servislerde geçiş, doküman + producer/consumer sözleşmesi birlikte güncellenerek aşamalı yapılmalıdır.