Ana içeriğe geç

Stream Buffer

Bu sayfa, stream_buffer:{device_id} keyinin keyspace seviyesindeki isletim sozlesmesini tanimlar.

Bu key, Qapu pipeline'inin servisler arasi omurga state kaydidir.

Key Pattern​

  • stream_buffer:{device_id}

Ornek:

  • stream_buffer:64000000C466EF70

Neden Kritik​

Bu key, Ingest ile baslayan veri isleme akisinda asagidaki servislerin ortak state alanidir:

  1. Ingest
  2. Stream
  3. Calibration
  4. Raw Writer
  5. Synthesis
  6. Window
  7. Observer (izleme, cleanup)

Not: Kapsamli alan yapisi ve ownership matrisi icin kanonik sozlesme kaynagi:

Bu sozlesme, mantiksal olarak stream buffer omurgasinin kanonik alan tanimini tasir.

Dokuman Seti​

Owner Service Modeli​

Ownerlik tek servis degildir; alan bazli ownerlik vardir.

  • Ingest: kaydi olusturur, ingest.* ve ilk buffers.measurements yazar.
  • Stream: stream.* yazar, stream_id baglar.
  • Calibration: calibration.* yazar, buffers.measurements in-place gunceller.
  • Raw Writer: raw_writer.* yazar.
  • Synthesis: synthesis.* yazar, buffers.synthesis doldurur.
  • Window: buffers.window ve final state bilgisini yazar.
  • Observer: terminal durumda temizler.

Kural: Her servis sadece kendi blogunu yazar; baska servisin semantik alanini degistiremez.

Read / Write Paths​

Read Path​

  • Stream, Calibration, Raw Writer, Synthesis, Window bu key'i birincil hizli kaynak olarak okur.
  • Alan eksigi veya key yoksa servis bazli DB fallback devreye girer.

Write Path​

  • Yazimlar stage bazli patch mantigiyla yapilir.
  • Basarili patch sonrasi state_version artar.
  • current_stage sadece basarili geciste ilerler.

Write Order (DB-Redis-Kafka)​

stream_buffer (stream buffer omurgasi) operasyonel state'tir; kalici dogruluk DB katmanindadir.

Stage bazli yazim duzeni:

  1. Ingest: raw DB write -> stream_buffer initialize -> Kafka tetikleme
  2. Stream: DB stream write -> stream_buffer stream patch -> Kafka
  3. Calibration: stream_buffer update -> Kafka (DB kural fallback olabilir)
  4. Raw Writer: DB segment write -> stream_buffer raw_writer patch -> Kafka
  5. Synthesis: DB turetilmis write -> stream_buffer synthesis patch -> Kafka
  6. Window: DB window write -> stream_buffer window patch -> Kafka

Kural: Kafka publish basarisiz olsa bile, DB ve Redis yazimi basariliysa veri kaybi yoktur; publish outbox/retry ile tekrar denenir.

TTL ve Temizlik Politikasi​

V1 onerisi:

  • Active processing TTL: 48h
  • Terminal durumda (completed, permanent_failed) anlik temizleme

Temizlik sorumlulugu:

  • Observer, akis terminal duruma geldiginde key'i siler.

Ek koruma:

  • TTL, observer cleanup kactiysa bellek birikimini sinirlar.

Failure ve Drift Senaryolari​

Senaryo A: Key yok​

  • Beklenen davranis: Servis failed event + replay/retry isaretler.
  • Etki: Aksam gecikir, dogruluk korunur.

Senaryo B: Stage uyumsuzlugu​

  • Beklenen davranis: Stage geri gitmez; ayni stage replay edilir.
  • Etki: Idempotent isleme korunur.

Senaryo C: Redis write hatasi​

  • Beklenen davranis: Stage failed event uretilir, retry kuyruğu devreye girer.
  • Etki: Geçici olarak zincir durur, veri kaybi olmaz.

Senaryo D: Orphan key birikimi​

  • Beklenen davranis: Observer cleanup + TTL fallback
  • Etki: Redis sisme riski kontrol altinda tutulur.

Reconciliation ve Rebuild​

Rebuild kaynaklari:

  1. Raw payload kaydi
  2. Stream ve typed measurement tablolari
  3. Synthesis/window kalici tablolari
  4. Event loglar (stage izi)

Rebuild stratejisi:

  1. Eksik stage belirlenir.
  2. En son basarili stage'den itibaren servis replay edilir.
  3. stream_buffer yeniden insa edilip pipeline kaldigi yerden devam eder.

Gozlemlenebilirlik Metrikleri​

  • stream_buffer_read_miss_total
  • stream_buffer_patch_fail_total
  • stream_buffer_stage_stuck_total
  • stream_buffer_orphan_key_total
  • stream_buffer_cleanup_total
  • stream_buffer_replay_requested_total

Alarm onerisi:

  • Miss oraninda ani artis
  • Stage stuck sayisinda artis
  • Cleanup oraninda dusus + orphan key artis

Kullanım Senaryolari​

1) Ingest baslangici​

  • Cihaz paketi kabul edilir
  • stream_buffer:{device_id} initialize edilir
  • Asama ingested olur

2) Stream baglama​

  • Stream DB kaydi olusur
  • stream_id key'e patch edilir
  • Asama streamed olur

3) Kalibrasyon in-place guncelleme​

  • buffers.measurements alanlari overwrite edilir
  • Yeni paralel buffer acilmaz

4) Observer terminal cleanup​

  • Akis completed veya permanent_failed olur
  • Key silinir

Capraz Referanslar​

  • Kapsamli alan/ownership sozlesmesi: /projects/qapu/services/redis/keyspace/stream-buffer/contract
  • Ornek asama akisi: /projects/qapu/services/redis/keyspace/stream-buffer/flow
  • Redis ana prensipleri: /projects/qapu/services/redis