Skip to content

priorities.md

Latest commit

 

History

History
285 lines (227 loc) · 9.96 KB

priorities.md

File metadata and controls

285 lines (227 loc) · 9.96 KB

Themis - Priorisierte Roadmap für Production Readiness

Stand: 6. April 2026, 22:15
Basis: IMPLEMENTATION_STATUS.md Audit-Ergebnisse

🎯 Entscheidungsmatrix: Nächste Schritte

Feature Impact Aufwand Risiko Prio Empfehlung
Prometheus Histogramme (kumulative Buckets) Mittel 2-4h Niedrig ✅ ERLEDIGT Quick Win - Abgeschlossen
HNSW Persistenz Hoch 1-2 Tage Mittel ✅ ERLEDIGT Datenverlust-Risiko eliminiert
COLLECT/GROUP BY MVP Hoch 3-5 Tage Mittel ✅ ERLEDIGT Basisfunktionalität implementiert
Vector Search HTTP Endpoint Hoch 1-2 Tage Niedrig ✅ ERLEDIGT API-Integration vollständig
OR Query Index-Merge Mittel 2-3 Tage Mittel ✅ ERLEDIGT DisjunctiveQuery implementiert
OpenTelemetry Tracing Mittel 3-5 Tage Niedrig ✅ ERLEDIGT Production-Debugging enabled
Inkrementelle Backups Niedrig 5-7 Tage Hoch 📋 P2 Nice-to-Have
RBAC (Basic) Hoch 7-10 Tage Hoch 📋 P2 Security (später)
Apache Arrow Integration Niedrig 10-15 Tage Mittel 📋 P3 Analytics (später)

Status Update (30. Oktober 2025, 13:50):

  • ✅ Alle P0-Features abgeschlossen!
  • ✅ P1 OpenTelemetry Tracing: VOLLSTÄNDIG IMPLEMENTIERT
    • ✅ Infrastruktur: Tracer-Wrapper, OTLP HTTP Exporter, CMake integration
    • ✅ HTTP-Handler instrumentiert (7 Endpoints)
    • ✅ QueryEngine instrumentiert (11 Methoden + Child-Spans)
    • ✅ AQL-Operator-Pipeline instrumentiert (parse, translate, for, filter, limit, collect, return, traversal+bfs)
    • ✅ Dokumentation aktualisiert (docs/tracing.md)
    • Build erfolgreich, Server-Test bestanden
    • ALLE P1-TASKS ABGESCHLOSSEN!

Abgeschlossene Features:

  • ✅ HNSW-Persistenz: Automatisches Save/Load implementiert
  • ✅ COLLECT/GROUP BY MVP: Parser + In-Memory Aggregation (COUNT, SUM, AVG, MIN, MAX)
  • ✅ Prometheus-Histogramme: Kumulative Buckets implementiert + validiert
  • ✅ Vector Search HTTP Endpoint: POST /vector/search mit k-NN Suche
  • ✅ OR Query Index-Merge: DisjunctiveQuery mit Index-Union
  • ✅ OpenTelemetry Distributed Tracing: End-to-End Instrumentierung (HTTP → QueryEngine → AQL Operators)

Legende:

  • 🔥 P0 = Kritisch (sofort/diese Woche) - ✅ ALLE ERLEDIGT
  • ⚠️ P1 = Wichtig (nächste 2 Wochen) - ✅ ALLE ERLEDIGT
  • 📋 P2 = Nice-to-Have (nächster Sprint) - NÄCHSTE PHASE
  • 📋 P3 = Backlog (zukünftig)

🚀 Empfohlene Reihenfolge (Batch 1: Diese Woche)

Option A: Quick Wins zuerst (Momentum aufbauen) ✅ ABGESCHLOSSEN

Tag 1-2:  Prometheus Histogramme (kumulative Buckets) ✅
Tag 2-4:  OR/NOT Index-Merge (Query-Flexibilität) ✅
Tag 5-7:  HNSW Persistenz (Datenverlust-Risiko eliminieren) ✅

Ergebnis: Alle P0-Features implementiert und getestet!

Batch 2: P1 Features (Diese/Nächste Woche)

Tag 1-2:  OpenTelemetry Tracing - Infrastruktur ✅
Tag 2-3:  OpenTelemetry Tracing - Instrumentierung (HTTP, Query)
Tag 4-5:  Jaeger Integration testen + Dokumentation

Option B: Strategische Features zuerst (Fundamentals)

Tag 1-5:  COLLECT/GROUP BY MVP (Basisfunktionalität)
Tag 6-7:  HNSW Persistenz (Datenverlust-Risiko)
Tag 8:    Prometheus Histogramme (Quick Win zum Abschluss)

Vorteil: Kernfunktionalität (Aggregationen) schnell verfügbar
Nachteil: Längerer initialer Entwicklungszyklus

Option C: Risiko-Minimierung zuerst (Defensive)

Tag 1-2:  HNSW Persistenz (Datenverlust-Risiko eliminieren)
Tag 3-7:  COLLECT/GROUP BY MVP (Basisfunktionalität)
Tag 8:    Prometheus Histogramme (Quick Win)

Vorteil: Kritische Risiken (Datenverlust) sofort adressiert
Nachteil: Komplexes Feature am Anfang (HNSW save/load)

🔍 Detaillierte Analyse: Top 3 Features

1️⃣ Prometheus Histogramme (kumulative Buckets)

Problem:

  • Aktuelle Implementation: Non-kumulative Buckets (jeder Bucket zählt nur seinen Range)
  • Prometheus-Spec: Buckets müssen kumulativ sein (le="100" = alle Werte ≤ 100)
  • Impact: Grafana/Prometheus-Tools zeigen falsche Percentiles

Lösung:

// Aktuell (FALSCH):
if (ms <= 1) page_bucket_1ms_++;
else if (ms <= 5) page_bucket_5ms_++;
// ...

// Korrekt (KUMULATIV):
if (ms <= 1) page_bucket_1ms_++;
if (ms <= 5) page_bucket_5ms_++;
if (ms <= 10) page_bucket_10ms_++;
// ... (jeder Wert inkrementiert ALLE passenden Buckets)

Aufwand:

  • Änderungen: http_server.cpp (recordLatency, recordPageFetch)
  • Tests: Smoke-Test erweitern (Bucket-Prüfung)
  • Doku: README.md aktualisieren
  • Geschätzt: 2-4 Stunden

DoD (Definition of Done):

  • recordLatency() verwendet kumulative Bucket-Logik
  • recordPageFetch() verwendet kumulative Bucket-Logik
  • Smoke-Test validiert: Wert 150ms → buckets 1,5,10,25,50,100,250,500,1000,5000,Inf alle ≥ 1
  • README.md Histogram-Beschreibung korrigiert

2️⃣ HNSW Persistenz (save/load)

Problem:

  • Vector-Index ist nur In-Memory
  • Server-Restart → alle Vektoren weg
  • Manuelles Rebuild nötig (Performance-Impact)

Lösung:

// HNSWlib API:
index_->saveIndex("data/vector_index_<collection>.bin");
index_->loadIndex("data/vector_index_<collection>.bin", space_, max_elements_);

Implementierung:

  1. Startup: VectorIndexManager::init() prüft auf existierende .bin, lädt wenn vorhanden
  2. Shutdown: VectorIndexManager::shutdown() speichert Index
  3. Background Save: Optional: Periodisches Save alle N Minuten
  4. Versioning: Filename-Schema: <collection>_v<version>.bin

Aufwand:

  • Code: vector_index.cpp (init/shutdown/save/load)
  • Tests: test_vector_index.cpp (save → restart → load → verify results)
  • Config: config.json (vector_save_interval_minutes)
  • Geschätzt: 1-2 Tage

DoD:

  • saveIndex() speichert bei Shutdown
  • loadIndex() lädt bei Startup (wenn vorhanden)
  • Test: Add 100 Vektoren → Restart → Search findet alle
  • Config-Option: vector_auto_save: true/false

3️⃣ COLLECT/GROUP BY MVP

Problem:

  • Aggregationen sind SQL/AQL-Standard-Feature
  • AST-Node (CollectNode) existiert, aber keine Executor-Integration
  • Queries wie SELECT city, COUNT(*) FROM users GROUP BY city unmöglich

Lösung (MVP-Scope):

// Beispiel:
FOR doc IN orders
  FILTER doc.created_at >= "2025-01-01"
  COLLECT city = doc.city
  AGGREGATE 
    total = SUM(doc.amount),
    count = COUNT()
  RETURN {city, total, count}

Implementierung:

  1. Parser: CollectNode parsing (bereits vorhanden in AST)
  2. Translator: handleCollect() in aql_translator.cpp
  3. Executor:
    • Hash-Map für Gruppierung: std::unordered_map<string, AggregateState>
    • Aggregat-Funktionen: COUNT, SUM, AVG, MIN, MAX
    • Streaming-Execution (keine Full-Scan-Materialisierung)
  4. Tests: Unit-Tests + HTTP-Integration-Tests

Aufwand:

  • Code: aql_translator.cpp, query_engine.cpp
  • Tests: test_aql_translator.cpp (mindestens 10 neue Tests)
  • Doku: docs/aql_syntax.md aktualisieren
  • Geschätzt: 3-5 Tage

MVP-Scope (Reduktion):

  • ✅ Einspaltige Gruppierung (COLLECT city = doc.city)
  • ✅ Basis-Aggregat-Funktionen (COUNT, SUM, AVG, MIN, MAX)
  • ❌ Mehrspaltige Gruppierung (später)
  • ❌ HAVING-Filter (später)
  • ❌ KEEP/WITH COUNT (später)

DoD:

  • COLLECT field = expr funktioniert
  • AGGREGATE count = COUNT() funktioniert
  • AGGREGATE sum = SUM(field) funktioniert
  • Unit-Tests: 10+ Test-Cases PASS
  • HTTP-Test: End-to-End GROUP BY Query
  • Doku: Beispiel in docs/aql_syntax.md

📊 Impact-Analyse

Business Value

  1. COLLECT/GROUP BY: ⭐⭐⭐⭐⭐ (Kernfunktionalität, Kundenerwartung)
  2. HNSW Persistenz: ⭐⭐⭐⭐ (Datenverlust-Risiko, Produktionsfähigkeit)
  3. Prometheus Histogramme: ⭐⭐⭐ (Observability, Ops-Qualität)

Technical Debt Reduction

  1. Prometheus Histogramme: ⭐⭐⭐⭐⭐ (Compliance-Fix, behebt Spec-Verletzung)
  2. HNSW Persistenz: ⭐⭐⭐⭐ (Architektur-Lücke schließen)
  3. COLLECT/GROUP BY: ⭐⭐⭐ (AST-Code-Completion)

Risk Mitigation

  1. HNSW Persistenz: ⭐⭐⭐⭐⭐ (Datenverlust-Risiko eliminieren)
  2. COLLECT/GROUP BY: ⭐⭐ (Feature-Lücke, kein direktes Risiko)
  3. Prometheus Histogramme: ⭐⭐ (Monitoring-Fehler, aber nicht kritisch)

✅ Empfehlung: Hybrid-Ansatz

Woche 1 (Tag 1-7):

🔥 Tag 1 (2-4h):    Prometheus Histogramme (Quick Win, Motivation)
🔥 Tag 1-3 (2 Tage): HNSW Persistenz (Risiko-Minimierung)
🔥 Tag 4-7 (4 Tage): COLLECT/GROUP BY MVP (Strategisch wichtig)

Rationale:

  1. Quick Win am Anfang: Momentum, sichtbarer Fortschritt nach 4h
  2. Risiko-Minimierung: HNSW-Persistenz vor Wochenende fertig
  3. Strategisches Feature: COLLECT/GROUP BY nutzt volle Woche

Erwartete Ergebnisse (Ende Woche 1):

  • ✅ Prometheus-konforme Histogramme
  • ✅ Vector-Index überleben Server-Restart
  • ✅ Basis-Aggregationen (COLLECT/COUNT/SUM) funktional
  • 📈 Production-Readiness-Score: ~35% → ~55%

📅 Backlog (Woche 2+)

Woche 2:

  • OR/NOT Index-Merge (2-3 Tage)
  • OpenTelemetry Tracing (3-5 Tage)

Sprint 2:

  • Inkrementelle Backups/WAL-Archiving
  • Automated Restore-Verification
  • Strukturierte JSON-Logs

Sprint 3:

  • RBAC (Basic)
  • Query/Plan-Cache
  • POST /config (Hot-Reload)

Langfristig:

  • Apache Arrow Integration
  • Phase 4 (Filesystem/Content) Start
  • Phase 7 (Security/Governance) Vollausbau

🎯 Entscheidung erforderlich

Bitte wählen:

  1. Option A: Quick Wins zuerst (Prometheus → OR/NOT → HNSW)
  2. Option B: Strategisch (COLLECT → HNSW → Prometheus)
  3. Option C: Risiko-Minimierung (HNSW → COLLECT → Prometheus)
  4. Empfehlung: Hybrid (Prometheus [Quick Win] → HNSW [Risiko] → COLLECT [Strategisch])

Oder eigene Priorisierung nennen.

Erstellt: 29. Oktober 2025
Nächster Review: Nach Abschluss von 3 P0-Features