Raw Writer Event Sözleşmeleri

Bu sayfa Raw Writer Servisi tarafından üretilen eventlerin payload sözleşmelerini, alan anlamlarını ve örneklerini toplu olarak verir.

Event Haritası

Event	Ne zaman üretilir?	Consumer	Amaç
raw.persisted.v1	Tüm segment yazımları başarıyla tamamlandığında	Sentez Servisi	DB yazımının tamamlandığını bildirmek
raw.failed.v1	Herhangi bir segment yazımı teknik hatayla sonlandığında	Ops/Replay Worker	Hata görünürlüğü ve replay tetiklemesi

Ortak Envelope

Raw Writer eventleri aşağıdaki ortak zarf yapısını kullanır:

{
  "event": "<name>.v1",
  "meta": {
    "schema_version": 1,
    "trace_id": "9f3f...",
    "producer_service": "raw-writer-service",
    "produced_at": "2026-03-11T15:22:10.090Z",
    "process_ms": 42
  },
  "context": {
    "device_id": "400000011D081B70",
    "stream_id": 9823412,
    "device_time": "2026-03-11T15:22:06Z",
    "stream_time": "2026-03-11T15:22:10Z"
  },
  "data": {},
  "error": null
}

Alan notları:

• meta.process_ms: Raw Writer servisinin bu event için uçtan uca işlem süresi (ms).
• context.device_time: Cihazın ürettiği zaman damgası.
• context.stream_time: Stream servisinde kaydın açıldığı sistem zamanı.

raw.persisted.v1

Tüm segment tablolarına yazım başarıyla tamamlandığında üretilir.

Alanlar

Alan	Tip	Zorunlu	Açıklama
event	string	Evet	Sabit değer: raw.persisted.v1
meta.schema_version	integer	Evet	Event şema sürümü
meta.trace_id	string	Evet	Dağıtık izleme kimliği
meta.producer_service	string	Evet	Sabit değer: raw-writer-service
meta.produced_at	datetime	Evet	Event üretim zamanı
meta.process_ms	integer	Evet	İşlem süresi (ms)
context.device_id	string	Evet	Cihaz kimliği
context.stream_id	integer	Evet	Stream kaydı kimliği
context.device_time	datetime	Evet	Cihaz zamanı
context.stream_time	datetime	Evet	Stream zamanı
data.persisted	boolean	Evet	Yazım tamamlandı mı
data.written_segments	string[]	Evet	Başarıyla yazılan segment adları
error	null	Evet	Başarı eventinde daima null

written_segments değerleri:

• voltage, current, power, energy — her pakette zorunlu
• device, register — her pakette zorunlu
• environment, water, location — pakette ilgili alan varsa eklenir- generic — hiçbir segment tablosuna girmeyen skalar değişken varsa eklenir

Örnek

{
  "event": "raw.persisted.v1",
  "meta": {
    "schema_version": 1,
    "trace_id": "9f3f...",
    "producer_service": "raw-writer-service",
    "produced_at": "2026-03-11T15:22:10.090Z",
    "process_ms": 42
  },
  "context": {
    "device_id": "400000011D081B70",
    "stream_id": 9823412,
    "device_time": "2026-03-11T15:22:06Z",
    "stream_time": "2026-03-11T15:22:10Z"
  },
  "data": {
    "persisted": true,
    "written_segments": [
      "voltage",
      "current",
      "power",
      "energy",
      "device",
      "register"
    ]
  },
  "error": null
}

raw.failed.v1

Herhangi bir segment yazımı teknik nedenle tamamlanamadığında üretilir.

Alanlar

Alan	Tip	Zorunlu	Açıklama
event	string	Evet	Sabit değer: raw.failed.v1
meta.schema_version	integer	Evet	Event şema sürümü
meta.trace_id	string	Evet	Dağıtık izleme kimliği
meta.producer_service	string	Evet	Sabit değer: raw-writer-service
meta.produced_at	datetime	Evet	Event üretim zamanı
meta.process_ms	integer	Evet	Hatanın oluştuğu ana kadar geçen süre
context.device_id	string	Evet	Cihaz kimliği
context.stream_id	integer	Evet	Stream kaydı kimliği
error.failed_stage	string	Evet	Sabit değer: raw_writer
error.error_code	string	Evet	Makine okunur hata kodu
error.error_message	string	Evet	İnsan okunur hata açıklaması
error.retryable	boolean	Evet	Hata retry edilebilir mi
error.failed_at	datetime	Evet	Hata oluşum zamanı
error.failed_table	string	Hayır	Hatanın oluştuğu segment tablosu

Örnek

{
  "event": "raw.failed.v1",
  "meta": {
    "schema_version": 1,
    "trace_id": "9f3f...",
    "producer_service": "raw-writer-service",
    "produced_at": "2026-03-11T15:22:10.130Z",
    "process_ms": 42
  },
  "context": {
    "device_id": "400000011D081B70",
    "stream_id": 9823412
  },
  "error": {
    "failed_stage": "raw_writer",
    "error_code": "RAW_DB_WRITE_FAIL",
    "error_message": "measurements_current insert failed",
    "retryable": true,
    "failed_at": "2026-03-11T15:22:10Z",
    "failed_table": "measurements_current"
  }
}

Hata Kodları Referansı

Kod	retryable	Açıklama
RAW_PAYLOAD_MISSING	false	device_buffer veya measurements bulunamadı
RAW_DB_WRITE_FAIL	true	Segment tablosuna yazım başarısız (geçici DB hatası olabilir)
RAW_SCHEMA_MISMATCH	false	Gelen veri beklenen şemayla uyuşmuyor