Zum Inhalt

Observability

Stand: 2026-05-25

Ziel

Agenten-, MCP- und Workflow-Aktivitaeten sollen nachvollziehbar werden, ohne sensible Daten zu protokollieren.

Minimalstandard

Jeder Agent-/MCP-Run protokolliert:

  • Zeitstempel
  • Run-ID
  • Toolname
  • Zielsystem
  • Aktionstyp
  • Ergebnisstatus
  • Dauer
  • Fehlerklasse
  • Git-Commit oder Branch, falls relevant

Nicht protokollieren:

  • Passwoerter
  • Tokens
  • Private Keys
  • vollstaendige Secret-Dateien
  • komplette Prompts mit Secrets

Zielarchitektur

Phase 1:

  • lokale strukturierte Logs pro MCP
  • n8n Execution History
  • Git-Commits als Audit Trail

Phase 2:

  • zentrale Logsammlung
  • einfache Dashboards
  • Healthchecks fuer MCPs und Dienste

Phase 3:

  • OpenTelemetry fuer MCPs und Agent Runtime
  • Loki/Grafana oder vergleichbarer Stack
  • Alerting ueber n8n/Mail/Teams

LiteLLM Logging und Callbacks

LiteLLM ist der zentrale Router für OpenCode und Open WebUI. Für produktive Nachvollziehbarkeit sollen Requests über technische Metadaten beobachtbar sein, ohne Promptinhalte oder Secrets dauerhaft zu speichern.

Ziel-Felder für künftige LiteLLM-Logs:

  • Request-ID
  • Model-Alias
  • Status
  • Dauer
  • Fehlerklasse oder Fehlergrund
  • Client/Key-Alias, soweit ohne Secret-Wert möglich

Nicht dauerhaft speichern:

  • vollständige Prompts
  • Antworten mit Kundendaten
  • API-Keys oder Tokens
  • hochgeladene Dateien

Entscheidung 2026-05-25: LiteLLM success_callback und failure_callback bleiben vorerst nicht aktiv, weil Standard-Callbacks je nach Zielsystem Prompt- oder Payload-Inhalte speichern können. Stattdessen wird zuerst ein minimaler lokaler Callback oder Log-Adapter vorbereitet, der nur die oben genannten Metadaten schreibt. Aktivierung erst nach separater Freigabe und Test mit Secret-/Prompt-Redaction.

Healthchecks

Zu ueberwachen:

  • Ollama API
  • LiteLLM Router
  • OpenCode MCP-Endpunkte
  • LiteLLM Router 10.222.70.20:4000
  • LiteLLM extern https://litellm.lanstyle.de/
  • Qdrant 10.222.70.20:6333
  • MCPHub 10.222.70.20:3000
  • MCPHub extern https://mcphub.lanstyle.de/
  • Lanstyle Tools API 10.222.70.20:3010
  • Gitea
  • MkDocs Deploy
  • NetBox
  • Vaultwarden
  • n8n
  • SearXNG
  • SearXNG extern https://search.lanstyle.de/
  • Open WebUI

Aktiver Healthcheck

Stand 2026-05-25:

  • n8n Workflow Lanstyle URL Healthcheck ist aktiv.
  • Workflow ID: bjNvXHMebs23cxrK
  • systemd Timer lanstyle-healthcheck.timer ist im n8n-LXC aktiv.
  • Letztes Ergebnis liegt unter /var/log/lanstyle-agent/healthcheck-latest.json.
  • Aktueller Status nach P1-Härtung: ok, 24 Checks.
  • LiteLLM wird zusätzlich mit echten Smoke-Tests pro Alias geprüft: lanstyle/architect, lanstyle/agent, lanstyle/agent-stable, lanstyle/fast und lanstyle/embed.
  • Qdrant Collection lanstyle_docs wird mit Status green und Punkteanzahl geprueft.
  • Qdrant Collection lanstyle_inventory wird mit Status green und Punkteanzahl geprueft.
  • Lanstyle Tools API wird ueber /health geprueft.
  • SearXNG wird intern von Open WebUI genutzt und extern über search.lanstyle.de geprueft.
  • Bei Fehlern sendet der Healthcheck eine SMTP-Mail an m.eberhardt@lanstyle.de und unterdrueckt Wiederholungen bis zur Erholung.

Der systemd-Healthcheck dient als robuste Betriebsebene. n8n bleibt zusaetzlich als sichtbarer Orchestrator und spaetere Benachrichtigungsstelle erhalten.

Inventory/RAG Refresh

Auf dem Agent-Runtime-LXC 259 ist ein systemd Timer vorgesehen:

  • Service: lanstyle-inventory-rag-refresh.service
  • Timer: lanstyle-inventory-rag-refresh.timer
  • Zeitplan: taeglich gegen 03:20 mit bis zu 15 Minuten Zufallsverzoegerung

Der Job:

  1. erzeugt secretfreie NPM-, NetBox- und Proxmox-Summaries,
  2. baut die Qdrant Collection lanstyle_inventory neu auf,
  3. erzeugt einen Qdrant Snapshot.

Secrets werden aus /opt/agent-runtime/.env und /opt/agent-runtime/mcphub/lanstyle-infra.env geladen. Beide Dateien bleiben lokal auf dem LXC und werden nicht ins Git geschrieben.

Letzter manueller Testlauf am 2026-05-25:

  • Status: erfolgreich
  • lanstyle_inventory: 1363 Punkte
  • letzter Snapshot: /opt/agent-runtime/backups/qdrant/lanstyle_inventory-8529590124808714-2026-05-25-17-00-13.snapshot

Inventar-Snapshots

Stand 2026-05-25 wurden erste secretfreie JSON-Summaries erzeugt:

  • NPM Proxy Hosts: agent-runtime/exports/npm/proxy-hosts-latest.summary.json
  • NetBox Summary: agent-runtime/exports/netbox/netbox-summary-latest.json
  • Proxmox Summary: agent-runtime/exports/proxmox/proxmox-summary-latest.json

Die zugehoerigen Skripte liegen unter agent-runtime/scripts/ und erwarten Secrets ausschliesslich aus Vaultwarden oder temporaeren Environment-Variablen.

Gesamt-Runner:

bw unlock --raw > /tmp/bw-session
export BW_SESSION
read -r BW_SESSION < /tmp/bw-session
agent-runtime/scripts/run-agent-runtime-exports.sh

Der Runner liest NPM- und NetBox-Secrets aus Vaultwarden, erzeugt aber nur secretfreie Summary-Dateien.

Agent Runtime Stack

Stand 2026-05-25:

  • LiteLLM, Qdrant, PostgreSQL, Redis und MCPHub laufen im LXC 259.
  • litellm.lanstyle.de und mcphub.lanstyle.de sind ueber NPM mit SSL und Access List Max erreichbar.
  • Produktive Secrets liegen in Vaultwarden im Eintrag Lanstyle / Agent Runtime Stack Secrets.
  • Der Stack kann mit agent-runtime/scripts/check-agent-runtime-stack.sh geprueft werden.
  • Der zentrale Healthcheck prueft die internen Runtime-Endpunkte, beide Qdrant-Collections, Lanstyle Tools API und die externen NPM-Endpunkte.
  • Der systemd-Healthcheck liest den Qdrant-Key aus /opt/lanstyle-agent/healthcheck.env im n8n-LXC. Die Datei ist lokal 0600 und wird nicht ins Git uebernommen.

Operations-Metriken

Die erste Observability-Schicht bleibt bewusst einfach und API-/Report-basiert.

Metrik Quelle Status
Workflow Runs /scheduled-workflows/history aktiv
Failed Runs /scheduled-workflows/trends aktiv
Approval Counts Controlled-Execution Audit geplant
Drift Counts State/Drift Layer aktiv für Testobjekte
Lock Conflicts SQLite Dependency Locks aktiv
Backup Readiness runtime_backup_validation_v1 aktiv
Model Errors LiteLLM Logs geplant
LiteLLM Failures LiteLLM Logs/API geplant
MCP Tool Failures MCPHub/Tools API Logs geplant

API:

GET /ops/observability

Prometheus/Loki werden erst empfohlen, wenn die JSON-/API-Reports nicht mehr ausreichen.