System

Der System-Tab umfasst Infrastruktur und Betrieb: Web-Einstellungen, Mail-Benachrichtigungen, System-Monitor (CPU, RAM, Disk, Services), Traces (OpenTelemetry), Backup & Restore, Performance-Cache, Integritätsprüfung, Selbsttest und das Änderungsprotokoll.

Sub-Tab: Web

Netzwerkeinstellungen für die Web-Oberflächen. Änderungen an Host und Ports erfordern einen Neustart der Services.

Feld	Typ	Standard	Beschreibung	Empfehlung
`Host`	Text	`0.0.0.0`	Bind-Adresse. `0.0.0.0` = alle Interfaces.	Standard belassen. Nur ändern, wenn der Dienst nur auf einem bestimmten Interface erreichbar sein soll.
`Port (Chat-UI)`	Zahl	`8501`	Port der Benutzer-Chat-Oberfläche.	Standard belassen.
`Admin-Port`	Zahl	`8502`	Port der Admin-Oberfläche.	Standard belassen.

Achtung: Nach Port-Änderungen müssen die systemd-Services (kiara.service, kiara-admin.service) neu gestartet werden. Firewall-Regeln entsprechend anpassen.

Sub-Tab: Mail

SMTP-Konfiguration für Admin-Benachrichtigungen. Das System sendet Mails bei Ausfällen (Ollama, Datenquellen) und optionale Statusberichte.

SMTP-Server

Feld	Typ	Standard	Beschreibung	Empfehlung
`Server`	Text	—	SMTP-Server-Adresse.	Beispiel: `smtp.firma.de`
`Port`	Zahl	`587`	SMTP-Port.	587 (STARTTLS) oder 465 (SSL). 25 nur im internen Netz.
`Verschlüsselung`	Dropdown	`starttls`	`none`, `starttls`, `ssl`.	starttls empfohlen.

Anmeldung

Feld	Typ	Beschreibung
`Benutzername`	Text	SMTP-Login (oft die E-Mail-Adresse).
`Passwort`	Passwort	Wird verschlüsselt gespeichert. Maskiert bei erneutem Laden.

Adressen

Feld	Typ	Pflicht	Beschreibung
`Absender`	Text	Ja	Von-Adresse (z.B. `kiara@firma.de`).
`Empfänger`	Text	Ja	Kommaseparierte Empfänger-Liste (z.B. `admin@firma.de, it@firma.de`).

Benachrichtigungen

Feld	Standard	Beschreibung
`Ollama nicht erreichbar`	An	Benachrichtigung wenn der Ollama-Server nicht antwortet.
`Datenquelle nicht erreichbar`	An	Benachrichtigung wenn eine Datenquelle (SMB, WebDAV, ...) nicht erreichbar ist.
`Indexierungsfehler`	An	Benachrichtigung bei fehlgeschlagenen Ingestion-Jobs.

Status-Reports

Feld	Standard	Beschreibung
`Automatische Status-Reports`	Aus	Sendet periodisch einen zusammenfassenden Bericht per Mail.
`Intervall`	`weekly`	`daily`, `weekly`, `monthly`.

Aktionen

Button	Beschreibung
Speichern	Speichert die Mail-Konfiguration.
Test-Mail senden	Sendet eine Test-Nachricht an die konfigurierten Empfänger.
Status-Report senden	Sendet sofort einen Status-Report (unabhängig vom Intervall).
Konfiguration löschen	Entfernt die gesamte Mail-Konfiguration. Keine Mails mehr.

Tipp: Nach dem Speichern immer »Test-Mail senden« klicken. SMTP-Probleme (falsche Credentials, Firewall, TLS-Mismatch) zeigen sich erst beim tatsächlichen Versand.

Sub-Tab: System-Monitor

Echtzeit-Überwachung des KIara-Servers mit Live-Metriken (CPU, RAM, Swap, Load, Netzwerk-Durchsatz), historischen Charts, Service-Management und Speicher-Übersicht. Ersetzt den früheren »Health & Monitoring«-Tab mit statischen Komponenten-Karten.

Live-Metriken (SSE-Stream)

Die Live-Ansicht zeigt KPI-Karten mit Echtzeit-Werten, die über einen Server-Sent Events (SSE) Stream mit 1 Sample/Sekunde aktualisiert werden. Kein Polling nötig — der Server pusht die Daten.

Metrik	Einheit	Beschreibung
CPU	%	CPU-Auslastung (1-Sekunden-Durchschnitt über alle Kerne).
RAM	GB / GB	Belegt / Gesamt des physischen Arbeitsspeichers.
Swap	GB / GB	Swap-Nutzung. Hohe Werte deuten auf RAM-Knappheit hin.
Load Average	1m / 5m / 15m	System-Last. Werte über der CPU-Kern-Anzahl deuten auf Überlastung hin.
Netzwerk	bytes/s (in/out)	Aktueller Netzwerk-Durchsatz (Sende- und Empfangsrate als Delta).
Plattenplatz	GB / GB	Belegt / Gesamt der Root-Partition (`/`).
Uptime	Tage/Stunden	Betriebszeit seit dem letzten Server-Neustart.
Top-5 Prozesse	MB	Die 5 Prozesse mit dem höchsten RAM-Verbrauch (PID, Name, RSS).
OS / Kernel	Text	Betriebssystem-Version und Kernel-Release.

Tipp: Der SSE-Stream reconnected automatisch bei Verbindungsabbruch (Browser-seitiges EventSource-Verhalten). Ein Keep-Alive alle 5 Sekunden verhindert Proxy-Timeouts bei inaktiven Verbindungen.

Charts & Zeitreihen

Neben den Live-Karten zeigt der Monitor Liniendiagramme (Chart.js) mit historischen Verläufen. Der Zeitraum ist wählbar:

Zeitraum	Datenquelle	Auflösung
1h	PostgreSQL (raw)	1 Datenpunkt/Minute
24h	PostgreSQL (raw)	1 Datenpunkt/Minute
30d	PostgreSQL (5min-Aggregate)	1 Datenpunkt/5 Minuten
1y	PostgreSQL (1h-Aggregate)	1 Datenpunkt/Stunde

Verfügbare Metrik-Gruppen

Gruppe	Serien
CPU	`cpu_percent`
RAM	`ram_used_bytes`, `ram_total_bytes`
Swap	`swap_used_bytes`, `swap_total_bytes`
Load	`load_1m`, `load_5m`, `load_15m`
Netzwerk	`net_sent_bps`, `net_recv_bps`
Disk	`disk_used_bytes`, `disk_total_bytes`

Services & Journal

Zeigt den Status aller KIara-systemd-Services und ermöglicht den Neustart direkt aus der UI (mit Bestätigungsdialog).

Service	Beschreibung
`kiara.service`	Chat-UI (Benutzer-Oberfläche, Port 8501).
`kiara-admin.service`	Admin-UI (Port 8502).
`kiara-worker.service`	Ingestion-Worker (Job-Queue-Verarbeitung).
`kiara-admin-chat.service`	Admin-Chat Backend.
`kiara-mcp.service`	MCP-Server (Port 8503, falls aktiviert).

Aktionen pro Service

Aktion	Beschreibung
Status anzeigen	Zeigt `active` / `inactive` / `failed`.
Neustart	Führt `systemctl restart` aus. Bestätigungsdialog erforderlich.

Letzte systemd-Fehler

Zeigt die letzten Fehler-Einträge aus journalctl für alle KIara-Services. Nützlich für die schnelle Fehlerdiagnose ohne SSH-Zugang.

Achtung: Vor einem Neustart von kiara-worker immer prüfen, ob ein Ingestion-Job läuft (siehe Jobs-Guide). Ein Neustart während einer Indexierung erzeugt einen Ghost-Job, der beim nächsten Start automatisch fortgesetzt wird, aber unnötige Wartezeit verursacht.

Speicher & Datenbanken

Zusätzlich zum Plattenplatz zeigt der Monitor die Größe der Datenbanken:

Metrik	Quelle	Aktualisierung
PostgreSQL-Größe	`pg_database_size()`	Alle 60 Sekunden (gecached).
Qdrant-Größe	Dateisystem-Scan des Data-Verzeichnisses	Alle 60 Sekunden (gecached, da rglob teuer).
Root-Partition	`psutil.disk_usage("/")`	Jede Sekunde (Live via SSE).

Konfiguration & Downsampling

Der System-Monitor läuft mit sinnvollen Defaults — keine Konfiguration nötig. Optional können Werte in kiara.yaml unter monitoring: angepasst werden:

Config-Key	Standard	Beschreibung
`persist_interval_seconds`	`60`	Intervall für DB-Writes (eine Zeile pro Minute).
`downsample_hour`	`3`	Uhrzeit (Stunde) für das tägliche Downsampling.
`raw_retention_hours`	`24`	Wie lange Raw-Daten (1/min) behalten werden, bevor sie in 5min-Aggregate komprimiert werden.
`retention_5min_days`	`30`	Wie lange 5min-Aggregate behalten werden.
`retention_1h_days`	`365`	Wie lange 1h-Aggregate behalten werden (danach gelöscht).
`qdrant_data_path`	(leer = Auto-Detect)	Pfad zum Qdrant-Datenverzeichnis für die Größen-Anzeige. Leer = Auto-Detect: Docker-Volume oder `/opt/qdrant/storage`.

Downsampling (3-Stufen-Komprimierung)

raw (1 Zeile/min)  ──[nach 24h]──▶  5min-AVG  ──[nach 30d]──▶  1h-AVG  ──[nach 1y]──▶  DELETE

Speicherverbrauch:
  Raw:  ~1.440 Zeilen/Tag
  5min: ~288 Zeilen/Tag
  1h:   ~24 Zeilen/Tag
  ≈ 312 Zeilen/Tag nach Downsampling

Tipp: Das Downsampling läuft als Background-Thread täglich um 03:00 Uhr (konfigurierbar). Es ist idempotent — wenn keine passenden Daten vorhanden sind, passiert nichts. Die historischen Daten in PostgreSQL belegen ca. ~120.000 Zeilen/Jahr — vernachlässigbar im Vergleich zu den übrigen KIara-Tabellen.

Backend-Probes (unverändert)

Die bisherigen Health-Endpoints bleiben für Load-Balancer und Orchestrierung erhalten:

/api/health — Vollständiger Health-Check (unauthentifiziert)
/api/health/ready — Readiness-Probe (Kubernetes-kompatibel)
/api/health/live — Liveness-Probe

Sub-Tab: Traces

OpenTelemetry-basiertes Tracing fuer Retrieval-, Agent- und Ingestion-Pipelines. Jede Anfrage bzw. Dateiverarbeitung wird als hierarchischer Trace aufgezeichnet (Root-Span → Child-Spans mit exakten Timing-Daten).

Konfiguration

# /etc/kiara/kiara.yaml
tracing:
  enabled: true              # Tracing aktivieren (default: false)
  exporter: postgresql       # "postgresql", "otlp" oder "both"
  retention_days: 7          # Auto-Cleanup aelterer Traces
  pipelines:                 # Per-Pipeline-Steuerung
    retrieval: true          # RAG-Queries + Retrieval
    agent: true              # Agent-Chain (ReAct-Loop)
    ingestion: true          # Ingestion-Pipeline
  chat_debug: false          # Trace-Timing-Bar in Chat-UI

Voraussetzung: Das Paket opentelemetry-sdk muss installiert sein (pip install 'kiara[tracing]'). Ohne SDK bleibt ein NoOp-Tracer aktiv — kein Fehler, null Overhead.

Drei Pipelines sind instrumentiert:

Pipeline	Root-Span	Typische Child-Spans
Retrieval	`rag_query`	`query_expansion`, `hybrid_retrieve`, `rerank`, `sibling_expansion`, `context_build`, `llm_generate`
Agent	`agent_query`	`agent_iteration`, `llm_step`, `tool_call`, `loop_detection`, `final_answer`
Ingestion	`ingest_file`	`load_content`, `chunk_and_collect`, `embed_batch`, `write_vectors`, `graph_extraction`

Einzelne Pipelines koennen per pipelines.*: false deaktiviert werden, z.B. um das Datenvolumen waehrend einer grossen Ingestion zu reduzieren. Der globale enabled: false-Schalter ueberschreibt alle Pipeline-Flags.

Trace Explorer

Der Trace Explorer ist im Sub-Tab Traces erreichbar und bietet:

Filter: Root-Span-Name, Mindest-Dauer, Status (OK/ERROR/UNSET), Zeitraum, Span-Name, Attribut-Suche
Wasserfall: Hierarchische Span-Visualisierung mit proportionalen Balken
Histogram: Bucket-basierte Dauer-Verteilung mit P50/P95/P99-Percentilen
Vergleich: Zwei Traces nebeneinander mit Span-fuer-Span-Diff (absolut + prozentual)
Export: CSV oder JSON, einzeln oder Bulk (bis 5.000 Eintraege)

Chat-Debug-Modus

Mit tracing.chat_debug: true erscheint in der Chat-UI ein Toggle (⏱). Bei aktiviertem Toggle wird unter jeder Antwort eine kompakte Timing-Bar angezeigt (z.B. Retrieval: 45ms · Reranking: 12ms · LLM: 830ms — 912ms) mit Link zum Trace Explorer.

Sicherheit: Chat-Debug-Endpoints pruefen Ownership — ein User sieht nur Traces seiner eigenen Anfragen. Admin-Konten haben keinen Zugriff auf Chat-Debug; der Trace Explorer im Admin-UI ist der richtige Weg.

OTLP-Export

Neben PostgreSQL koennen Spans per OTLP/gRPC an externe Plattformen (Grafana Tempo, Jaeger, Datadog, etc.) exportiert werden:

tracing:
  enabled: true
  exporter: both             # PostgreSQL + OTLP parallel
  otlp:
    endpoint: "http://10.0.12.30:4317"
    insecure: true           # Kein TLS (internes Netz)

Exporter-Wert	Ziel	Anwendungsfall
`postgresql`	Lokale `traces`-Tabelle	Standard — Trace Explorer
`otlp`	Externer Collector (gRPC)	Grafana Tempo, Jaeger, etc.
`both`	Beide parallel	Uebergangsphase

Installation: OTLP-Export erfordert ein zusaetzliches Paket: pip install 'kiara[tracing-otlp]'. Fehlt das Paket, faellt KIara automatisch auf den verbleibenden Exporter zurueck — kein Absturz.

Sub-Tab: Backup & Restore

Vollständige Sicherung und Wiederherstellung: Datenbank, Konfiguration, Templates und optional die Vektordatenbank. Backups enthalten SHA256-Prüfsummen.

Backup erstellen

Feld	Typ	Standard	Beschreibung
`VectorDB-Daten einschließen`	Checkbox	An	Wenn aktiviert, werden Qdrant-Snapshots ins Backup einbezogen. Erhöht die Backup-Größe erheblich, spart aber bei Restore die Neuindexierung.

Tipp — Backup-Strategie:

Tägliches Backup ohne VectorDB: Schnell und klein (~MBs). Bei Restore muss neu indexiert werden.
Wöchentliches Backup mit VectorDB: Größer (GBs bei vielen Chunks), aber vollständiges Restore ohne Neuindexierung.

Backup-Liste

Spalte	Beschreibung
Dateiname	Dateiname (z.B. `kiara_backup_2026-03-29_14-30.tar.gz`).
Größe	Dateigröße in MB.
Erstellt	Erstellungszeitpunkt.
Aktionen	Wiederherstellen (mit Bestätigung).

Achtung: Die Wiederherstellung überschreibt die aktuelle Datenbank und Konfiguration. Alle Änderungen seit dem Backup-Zeitpunkt gehen verloren. Vor einem Restore ein aktuelles Backup erstellen!

Sub-Tab: Performance (Cache)

Query-Cache-Statistiken. Der Cache beschleunigt wiederkehrende Anfragen und wird bei Neuindexierung automatisch invalidiert. Aktualisiert sich alle 10 Sekunden.

KPI-Widgets

KPI	Beschreibung
Cache aktiv	Ja/Nein — ob der Query-Cache aktiviert ist.
Einträge	Aktuelle Belegung vs. Maximum (z.B. `42 / 256`).
Hit-Rate	Anteil der Anfragen, die aus dem Cache beantwortet wurden.
Hits / Misses	Absolute Zähler: Cache-Treffer vs. Cache-Fehlschläge.
TTL	Time-to-Live eines Cache-Eintrags in Sekunden.

Aktionen

Button	Beschreibung
Cache leeren	Invalidiert alle Cache-Einträge sofort. Bestätigung erforderlich. Nützlich nach manuellen Datenbank-Änderungen oder Config-Updates.

Tipp: Eine Hit-Rate unter 10% deutet darauf hin, dass die meisten Anfragen einmalig sind — der Cache bringt wenig Nutzen. Eine Hit-Rate über 30% zeigt, dass der Cache signifikant zur Antwortgeschwindigkeit beiträgt.

Sub-Tab: Integrität

Prüft die Konsistenz aller 4 Datenschichten (Qdrant, Elasticsearch, chunk_datasources, file_hashes). Die vollständige Dokumentation der Checks und Reparatur-Aktionen findest du im VektorDB-Guide → Integritätsprüfung.

Prüfungen (Kurzübersicht)

Button	Beschreibung	Laufzeit
Vollprüfung starten	5 Checks: Layer-Counts, DS-Coverage, ES-Duplikate, Orphan-Chunks, Overlapping DS.	Minuten (Background, Polling alle 2s).
Schnell-Check	Nur Layer-Counts vergleichen.	Sekunden (synchron).

Reparatur-Aktionen (bei Befund)

Aktion	Beschreibung
ds_ids synchronisieren	Schreibt ds_ids-Payload in Qdrant aus chunk_datasources neu.
Statistiken korrigieren	Aktualisiert chunk_count in datasource_embeddings.
Verwaiste Chunks löschen	Löscht Chunks ohne chunk_datasources-Zuordnung (destruktiv).

Sub-Tab: Selbsttest

Führt die gesamte Testsuite aus und prüft alle Systemkomponenten auf korrekte Funktion. Läuft im Hintergrund mit Live-Fortschrittsanzeige (Polling alle 1,5s).

Fortschrittsanzeige (während Test)

Fortschrittsbalken mit Prozentsatz
Aktueller Test-Name
Live-Zähler: ✓ bestanden, ✗ fehlgeschlagen, ⚠ Fehler, ⊘ übersprungen

Ergebnis-Anzeige (nach Abschluss)

KPI-Leiste: Bestanden / Fehlgeschlagen / Fehler / Übersprungen / Dauer
Fehlgeschlagene Tests (aufgeklappt): Name + Detail-Ausgabe
Bestandene Tests (eingeklappt): Multi-Column-Liste
Übersprungene Tests (eingeklappt): Multi-Column-Liste

Tipp: Übersprungene Tests bedeuten, dass die jeweilige Komponente nicht konfiguriert ist (z.B. LDAP-Tests ohne LDAP-Config, Cloud-Tests ohne API-Key). Das ist kein Fehler — es zeigt nur, dass der Test nicht anwendbar ist.

Sub-Tab: Änderungen (Changelog)

Chronologisches Protokoll aller Konfigurationsänderungen. Zeigt wer wann was geändert hat — egal ob über die GUI oder den Admin-Chat.

Filter

Filter	Typ	Beschreibung
Bereich	Dropdown	Filtert nach Änderungs-Bereich (z.B. users, datasources, ki, system). Dynamisch geladen.
Quelle	Dropdown	`Alle`, `GUI`, `Chat`.

Tabellen-Spalten

Spalte	Beschreibung	Sortierbar
Zeitstempel	Datum und Uhrzeit der Änderung.	Ja
Benutzer	Wer die Änderung vorgenommen hat.	Ja
Bereich	Betroffener Bereich (users, datasources, ki, ...).	Ja
Aktion	Badge: Erstellt (grün), Aktualisiert (blau), Gelöscht (rot).	Ja
Quelle	Badge: GUI oder Chat.	Ja
Ziel	Betroffenes Objekt (z.B. Datenquellen-Name, Template-Name).	Ja
Feld	Geändertes Feld (z.B. `name`, `is_active`).	Ja

Detail-Ansicht (Expandable)

Klick auf eine Zeile zeigt die Vorher/Nachher-Werte im Vergleich: alter Wert links, neuer Wert rechts. Bei JSON-Feldern werden die Werte formatiert dargestellt.

Tipp: Der Changelog erfasst Änderungen sowohl aus der GUI als auch aus dem Admin-Chat. Das bedeutet: Wenn ein Admin per Chat »Deaktiviere Benutzer 5« sagt, erscheint die Änderung hier mit Quelle »Chat«. Nützlich für die Nachvollziehbarkeit bei mehreren Admins.

Netzwerk-Diagnose (Admin-Chat)

Netzwerk-Diagnose-Tools sind über den Admin-Chat verfügbar (kein eigener Sub-Tab). Sie ermöglichen die Fehlersuche bei Verbindungsproblemen direkt aus der Admin-UI.

Tool	Beschreibung	Beispiel-Prompt
`network.ping`	ICMP-Ping (1–10 Pakete).	»Ping 10.0.12.16«
`network.portscan`	TCP-Port-Scan (via nmap oder Socket-Fallback).	»Prüfe ob Port 6333 auf localhost offen ist«
`network.dns`	DNS-Auflösung (A, AAAA, MX, CNAME, PTR).	»DNS-Lookup für mail.firma.de«
`network.smb_discover`	Verfügbare SMB-Freigaben auflisten.	»Welche Freigaben hat der Server fileserver01?«
`network.webdav_check`	WebDAV-Erreichbarkeit prüfen (OPTIONS/PROPFIND, DAV-Compliance).	»Ist der Nextcloud-Server erreichbar?«
`network.http_check`	HTTP(S)-Erreichbarkeit testen (HEAD/GET, Status, RTT).	»Ist http://10.0.12.16:11434 erreichbar?«
`network.traceroute`	Netzwerkpfad zu einem Host (max. 20 Hops).	»Traceroute zu 10.0.12.16«

Tipp: Die Netzwerk-Tools sind besonders nützlich bei der Ersteinrichtung von Datenquellen-Konnektoren (SMB, WebDAV, IMAP) — sie ermöglichen die Fehlersuche ohne SSH-Zugang zum KIara-Server.

API-Endpunkte

Die vollständige API-Referenz wird dynamisch aus der Admin-Registry generiert:

System-API — Health, Settings, Metriken, Changelog
Monitoring-API — SSE-Stream, History, Services, Journal
Mail-API — SMTP-Konfiguration, Test-Mail, Status-Reports
Backup-API — Erstellen, Auflisten, Wiederherstellen
Cache-API — Statistiken, Leeren
Integrity-API — Prüfungen, Reparaturen
Testsuite-API — Starten, Status
Netzwerk-API — Ping, DNS, Portscan, Traceroute, SMB, WebDAV, HTTP
Services-API — systemd-Service-Steuerung