Synthesis Event Sozlesmeleri

Bu sayfa Synthesis Servisi tarafindan tuketilen/uretilen eventlerin payload sozlesmelerini, zorunlu alanlarini ve versiyonlama kurallarini toplu olarak verir.

Event Haritasi

Event	Ne zaman kullanilir?	Producer	Consumer	Amac
raw.persisted.v1	Sentez akisini tetiklemek icin tuketilir	Raw Writer Servisi	Synthesis Servisi	Islenecek stream baglamini almak
synth.ready.v1	Sentez hesabi + yazimlar tamamlandiginda uretilir	Synthesis Servisi	Window Servisi	Pencere hesabini tetiklemek
synth.failed.v1	Sentez adimi teknik hatayla sonlandiginda uretilir	Synthesis Servisi	Ops/Replay Worker	Hata gorunurlugu ve tekrar isleme

Ortak Envelope

Synthesis eventleri asagidaki ortak zarf yapisini kullanir:

{
  "event": "<name>.v1",
  "meta": {
    "schema_version": 1,
    "trace_id": "9f3f...",
    "producer_service": "synthesis-service",
    "produced_at": "2026-04-12T09:10:11.102Z",
    "process_ms": 22
  },
  "context": {
    "device_id": "400000011D081B70",
    "stream_id": 9823412,
    "device_time": "2026-04-12T09:10:08Z",
    "stream_time": "2026-04-12T09:10:11Z"
  },
  "data": {},
  "error": null
}

Alan notlari:

• meta.process_ms: Synthesis servisinin bu event icin uctan uca islem suresi (ms).
• context.device_time: Cihazin olcum zaman damgasi.
• context.stream_time: Stream katmaninda kaydin acildigi sistem zamani.

Observability Ownership

Bu dokuman, Synthesis event kontratini ve SLI alanlarini tanimlar. Sayisal SLO/SLA hedefleri ile alarm esikleri Observer Servisi tarafinda yonetilir.

Detaylar icin Observer Servisi sayfasina bakiniz.

Input Event

raw.persisted.v1

Synthesis servisi bu eventi tetikleyici olarak tuketir.

Alan	Tip	Zorunlu	Aciklama
event	string	Evet	Sabit deger: raw.persisted.v1
meta.schema_version	integer	Evet	Event sema surumu
meta.trace_id	string	Evet	Dagitik izleme kimligi
meta.producer_service	string	Evet	Beklenen deger: raw-writer-service
meta.produced_at	datetime	Evet	Event uretim zamani
context.device_id	string	Evet	Cihaz kimligi
context.stream_id	integer	Evet	Islenecek stream kaydi
context.device_time	datetime	Evet	Cihaz zamani
context.stream_time	datetime	Evet	Stream zamani

synth.ready.v1

Sentez hesabi tamamlanip Redis synthesis ve sentez tablolari basariyla guncellendiginde uretilir.

Alanlar

Alan	Tip	Zorunlu	Aciklama
event	string	Evet	Sabit deger: synth.ready.v1
meta.schema_version	integer	Evet	Event sema surumu
meta.trace_id	string	Evet	Dagitik izleme kimligi
meta.producer_service	string	Evet	Sabit deger: synthesis-service
meta.produced_at	datetime	Evet	Event uretim zamani
meta.process_ms	integer	Evet	Islem suresi (ms)
context.device_id	string	Evet	Cihaz kimligi
context.stream_id	integer	Evet	Stream kaydi kimligi
context.device_time	datetime	Evet	Cihaz zamani
context.stream_time	datetime	Evet	Stream zamani
data.rule_version	string	Hayir	Kullanilan kural snapshot versiyonu
data.written_tables[]	string[]	Evet	Yazilan sentez tablolari
data.redis_patch_applied	boolean	Evet	synthesis patch basari durumu
error	null	Evet	Basari eventinde daima null

Ornek

{
  "event": "synth.ready.v1",
  "meta": {
    "schema_version": 1,
    "trace_id": "9f3f...",
    "producer_service": "synthesis-service",
    "produced_at": "2026-04-12T09:10:11.182Z",
    "process_ms": 22
  },
  "context": {
    "device_id": "400000011D081B70",
    "stream_id": 9823412,
    "device_time": "2026-04-12T09:10:08Z",
    "stream_time": "2026-04-12T09:10:11Z"
  },
  "data": {
    "rule_version": "ruleset-2026.04.10",
    "written_tables": [
      "synthesis_voltage",
      "synthesis_current",
      "synthesis_power",
      "synthesis_energy"
    ],
    "redis_patch_applied": true
  },
  "error": null
}

synth.failed.v1

Sentez adimi teknik nedenle tamamlanamadiginda uretilir.

Alanlar

Alan	Tip	Zorunlu	Aciklama
event	string	Evet	Sabit deger: synth.failed.v1
meta.schema_version	integer	Evet	Event sema surumu
meta.trace_id	string	Evet	Dagitik izleme kimligi
meta.producer_service	string	Evet	Sabit deger: synthesis-service
meta.produced_at	datetime	Evet	Event uretim zamani
meta.process_ms	integer	Evet	Hatanin olustugu ana kadar gecen sure
context.device_id	string	Evet	Cihaz kimligi
context.stream_id	integer	Evet	Stream kaydi kimligi
error.failed_stage	string	Evet	Pipeline asamasi (input_resolution, rule_resolution, persist, publish)
error.error_code	string	Evet	Makine okunur hata kodu
error.error_message	string	Evet	Insan okunur hata aciklamasi
error.retryable	boolean	Evet	Yeniden denenebilirlik bilgisi
error.failed_at	datetime	Evet	Hata olusum zamani

Ornek

{
  "event": "synth.failed.v1",
  "meta": {
    "schema_version": 1,
    "trace_id": "9f3f...",
    "producer_service": "synthesis-service",
    "produced_at": "2026-04-12T09:10:11.191Z",
    "process_ms": 24
  },
  "context": {
    "device_id": "400000011D081B70",
    "stream_id": 9823412
  },
  "error": {
    "failed_stage": "rule_resolution",
    "error_code": "RULE_NOT_FOUND",
    "error_message": "No active synthesis rule found for stream_id=9823412",
    "retryable": false,
    "failed_at": "2026-04-12T09:10:11Z"
  }
}

Zorunlu Alan Dogrulama Kurallari

Synthesis servisinde event kabul/uretimi asamasinda asagidaki kontroller uygulanir:

Kural	Uygulama
event bos olamaz	Bos/yanlis event adinda event reddedilir
meta.schema_version zorunlu	Desteklenmeyen versiyonlarda synth.failed.v1 (UNSUPPORTED_SCHEMA_VERSION)
meta.trace_id zorunlu	Yoksa yeni trace_id uretilir ve warning log atilir
context.device_id zorunlu	Yoksa islem durur (DEVICE_ID_MISSING)
context.stream_id zorunlu	Yoksa islem durur (STREAM_ID_MISSING)
synth.ready.v1 icin error=null	Aksi durumda payload gecersiz sayilir
synth.failed.v1 icin error.* zorunlu	error_code/error_message/retryable/failed_stage eksik olamaz

Versiyonlama ve Geriye Donuk Uyumluluk

• Bu dokumanda aktif surum v1 ve meta.schema_version=1 kabul edilir.
• Geriye donuk uyumlu degisiklikler (optional alan ekleme) mevcut v1 altinda yapilir.
• Geriye donuk uyumsuz degisikliklerde yeni event surumu acilir (synth.ready.v2, synth.failed.v2).
• Tuketici servisler en az bir gecis periyodu boyunca v1 + v2 birlikte dinlemelidir.
• Surum gecislerinde producer tarafinda cift yayin (dual publish) ve kontrat testi zorunludur.

Hata Kodlari Referansi

Aşağıdaki hata kodları synth.failed.v1 içinde kullanılabilir:

• STREAM_ID_MISSING
• DEVICE_ID_MISSING
• INPUT_SET_INCOMPLETE
• RULE_NOT_FOUND
• SYNTHESIS_WRITE_FAILED
• UNSUPPORTED_SCHEMA_VERSION
• UNEXPECTED