Skip to main content

Event Envelope Standardı

Bu doküman, Qapu sistemindeki tüm Kafka eventleri için geçerli olan zorunlu zarf (envelope) yapısını tanımlar. Her servisin event kataloğu bu dizin altındaki alt sayfalarda tutulur.

Topic Standardı

Bu sayfa yalnız envelope yapısını tanımlar. Topic adlandırma, DLQ politikası ve retention kuralları için Kafka Topic Standard sayfasına bakınız.

Kapsam​

  • Bu sayfa, sistem genelindeki tüm eventlerin paylaştığı zarf yapısının tek kaynak referansıdır.
  • Her servis kendi event içeriğini (data bloğu) kendi event-contracts dokümanında tanımlar.
  • Bu dizin altındaki sayfalar, event bazlı çapraz referans (topic, producer, consumer) kataloğudur.

Zorunlu Envelope Yapısı​

{
  "event": "service.action.v1",
  "meta": {
    "trace_id": "abc-1234",
    "producer_service": "service-name",
    "produced_at": "2026-04-15T10:00:00.000Z",
    "process_ms": 12
  },
  "context": {},
  "data": {},
  "error": null
}

Alan Tanımları​

Üst Düzey Alanlar​

AlanTipZorunluAçıklama
eventstringEvetGlobally unique event adı: <service>.<action>.v<n>
metaobjectEvetTeknik metadata bloğu
contextobjectEvetİş bağlamı (cihaz, stream, SIM vb.)
dataobjectEvetEvent'e özgü payload; event türüne göre şema değişir
errorobject | nullEvetHata durumunda doldurulur; başarılı eventta null

meta Alanları​

AlanTipZorunluAçıklama
meta.trace_idstring (UUID v7)EvetDağıtık izleme kimliği; event zinciri boyunca sabit taşınır. Ingest servisi oluşturur; downstream servisler pass-through yapar
meta.producer_servicestringEvetÜretici servis kimliği (örn: ingest-service)
meta.produced_atdatetime (ISO 8601)EvetEvent üretim zamanı (UTC)
meta.process_msintegerHayırServisin bu event için uçtan uca işlem süresi

context Alanları​

Tüm eventlerde aşağıdaki şema kullanılır. Null atanabilen alanlar ilgili flowda null olur.

AlanTipZorunluAçıklama
context.device_idstringEvetCihazın DS28C kimliği
context.raw_idinteger | nullHayırRaw pakete ait raw_packets.id
context.stream_idinteger | nullHayırStream adım kaydına ait streams.id
context.device_timedatetime (ISO 8601)EvetCihazdan gelen ölçüm/event zamanı
context.stream_timedatetime (ISO 8601) | nullHayırServis tarafında kaydın işleme zamanı
context.iccidstring | nullHayırSIM'in ICCID'si (heartbeat/connectivity)
context.imeistring | nullHayırModem IMEI numarası
context.firmwarestring | nullHayırCihazda çalışan firmware versiyonu

error Alanı (Hata Eventlerinde)​

AlanTipZorunluAçıklama
error.codestringEvetMakineyle okunabilir hata kodu
error.messagestringEvetİnsan okunabilir açıklama
error.stagestringEvetHatanın oluştuğu servis aşaması
error.retryablebooleanEvetYeniden denenebilir mi?

Event Adlandırma Kuralı​

Format: <service>.<action>.v<n>

  • <service>: Üretici servisin canonical adı (örn: stream, calibration, window)
  • <action>: İşin sonucunu tanımlayan kısa eylem (örn: created, ready, failed, committed)
  • v<n>: Semantik versiyon; breaking payload değişikliğinde arttırılır

Örnekler:

  • stream.created.v1
  • calibration.ready.v1
  • window.ready.v1
  • egress.sent.v1

Versiyon Politikası​

  • Mevcut bir event'e zorunlu olmayan yeni alan eklenmesi breaking change değildir; v1 devam eder.
  • Mevcut alanlarda tip değişikliği, alan silinmesi veya zorunlu alan eklenmesi breaking change'dir → event adı v2 olur.
  • v1 ve v2 bir süre birlikte taşınabilir; consumer geçişi tamamlanana kadar producer her ikisini de üretebilir.

Event Kataloğu​

Aşağıdaki tablo sistemdeki tüm eventleri servis ve topic bazlı özetler. Detaylar ilgili servis sayfasında bulunur.

EventTopicProducerBaşlıca Consumer
ingest.accepted.v1qapu.ingestIngestStream
device.ingest_duplicate_detected.v1qapu.ingestIngestObserver/Ops
stream.created.v1qapu.streamStreamCalibration
stream.failed.v1qapu.streamStreamObserver
device.inventory.created.v1qapu.streamStreamAudit
device.inventory.updated.v1qapu.streamStreamAudit
modem.inventory.created.v1qapu.streamStreamAudit
device.modem.changed.v1qapu.streamStreamAudit
sim.inventory.created.v1qapu.streamStreamAudit
device.sim.changed.v1qapu.streamStreamAudit
device.firmware.recorded.v1qapu.streamStreamAudit
device.firmware.changed.v1qapu.streamStreamAudit
stream.message_type.unmapped.v1qapu.streamStreamOps
calibration.ready.v1qapu.calibrationCalibrationRaw Writer
calibration.failed.v1qapu.calibrationCalibrationObserver
raw.persisted.v1qapu.raw-writerRaw WriterSynthesis
raw.failed.v1qapu.raw-writerRaw WriterObserver
synth.ready.v1qapu.synthesisSynthesisWindow
synth.failed.v1qapu.synthesisSynthesisObserver
window.ready.v1qapu.windowWindowRule, Egress, Ledger, API
window.failed.v1qapu.windowWindowObserver
rule.triggered.v1qapu.ruleRuleAction
rule.reset.v1qapu.ruleRuleAction
rule.completed.v1qapu.ruleRuleObserver
action.execute.requested.v1qapu.actionRule/ActionCommunication, Action
action.executed.v1qapu.actionActionObserver
action.failed.v1qapu.actionActionObserver
communication.sent.v1qapu.communicationCommunicationAutomation, Observer
communication.failed.v1qapu.communicationCommunicationObserver
automation.command.requested.v1qapu.automationAutomationCommunication, Egress
automation.job.completed.v1qapu.automationCommunicationAutomation, Egress
automation.job.failed.v1qapu.automationCommunication/AutomationObserver, Egress
heartbeat.metrics.updated.v1qapu.heartbeatHeartbeatObserver, API
heartbeat.status.changed.v1qapu.heartbeatHeartbeatObserver, Alarm
heartbeat.failed.v1qapu.heartbeatHeartbeatObserver
observer.buffer.duplicate.v1qapu.observerObserverDashboard, Audit
observer.buffer.replaced.v1qapu.observerObserverDashboard, Audit
observer.retry.requested.v1qapu.observerObserverRetry Worker
observer.escalated.v1qapu.observerObserverAlertingSystem, Dashboard
observer.completed.v1qapu.observerObserverAnalytics, Dashboard
ledger.committed.v1qapu.ledgerLedgerObserver, Egress, Audit
ledger.failed.v1qapu.ledgerLedgerObserver
egress.sent.v1qapu.egressEgressObserver
egress.failed.v1qapu.egressEgressObserver, DLQ
firmware.download.completed.v1qapu.fotaFOTAObserver
firmware.download.failed.v1qapu.fotaFOTAObserver