From dcdfb1bc9ec4335abbbd0349f6b1706ad35eef8a Mon Sep 17 00:00:00 2001
From: Elton Turing <elton@42i.org>
Date: Sat, 5 Sep 2026 16:16:22 +0200
Subject: [PATCH] llmrouter README: die vier Wege ins Log (stats, zuordnung,
 jsonl/changes/sqlite, Journal)

Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
---
 README.md | 48 +++++++++++++++++++++++++++++++++++++++++-------
 1 file changed, 41 insertions(+), 7 deletions(-)

diff --git a/README.md b/README.md
index 58170f5..cd08d3a 100644
--- a/README.md
+++ b/README.md
@@ -133,17 +133,51 @@ Der erste Lauf mit leerem State prüft jeden Alias unter Last, das ist gewollt.
 ## Log und Statistik
 
 Je Anfrage eine Zeile in `log/requests.jsonl` und in `log/requests.sqlite`:
-Key, Alias, angefragter Name, tatsächliches Modell, Effort, Tokens
-(prompt/completion/cached), **Kosten wie von OpenRouter gemeldet**
-(`usage.cost`, auch im Stream über den letzten Chunk). Lokale Upstreams haben
-keine Kosten, das Feld bleibt leer, wir erfinden keine Preise.
+Key, angefragter Name, aufgelöster Alias, tatsächliches Modell, Effort, Pfad,
+Status, Dauer, Tokens (prompt/completion/cached), **Kosten wie von OpenRouter
+gemeldet** (`usage.cost`, auch im Stream über den letzten Chunk und über den
+Messages-Endpunkt). Lokale Upstreams und die LiteLLM-Durchreiche haben keine
+Kosten, das Feld bleibt leer, wir erfinden keine Preise. Die Antwort trägt
+`x-llmrouter-model`, damit ein Client sieht, was wirklich lief.
+
+### Vier Wege ins Log
+
+**1. Statistik je Tag und Key** — vom Mac aus, Admin-Key aus OpenBao
+(`jessie/llmrouter admin_key`):
 
 ```bash
-bun run src/stats.ts 7        # Tag × Key: Anfragen, Tokens, Kosten, Modelle
-curl -H "Authorization: Bearer $ADMIN_KEY" http://llm.lan:4010/stats?days=7
+curl -s "http://llm.lan:4010/stats?days=7" \
+  -H "Authorization: Bearer $(~/.agents/bin/secret get jessie llmrouter admin_key)" | python3 -m json.tool
 ```
 
-Die Antwort trägt `x-llmrouter-model`, damit ein Client sieht, was wirklich lief.
+**2. Aktuelle Zuordnung** — konfigurierte Aliasse und alle bisher angefragten
+`alt/`-Referenzen mit Ziel, Effort, Indexen, Preis und Zeitpunkt:
+
+```bash
+curl -s http://llm.lan:4010/zuordnung \
+  -H "Authorization: Bearer $(~/.agents/bin/secret get jessie llmrouter admin_key)" | python3 -m json.tool
+```
+
+**3. Einzelne Anfragen** auf dem Host (LXC 185020, `/srv/llmrouter/log`):
+
+```bash
+ssh s18p1.lan 'pct exec 185020 -- tail -20 /srv/llmrouter/log/requests.jsonl'
+ssh s18p1.lan 'pct exec 185020 -- cat /srv/llmrouter/log/changes.log'      # jeder Modellwechsel der Auflösung
+ssh s18p1.lan 'pct exec 185020 -- bash -c "cd /srv/llmrouter && ./llmrouter-stats 7"'   # Tagesstatistik als Tabelle
+```
+
+`requests.sqlite` steht für eigene Abfragen offen (Tabelle `requests`, Spalten
+wie die JSONL-Felder).
+
+**4. Dienst-Journal** — Start, Auffrischen, abgewiesene Keys (401 mit
+Key-Länge und Präfix), Upstream-Fehler:
+
+```bash
+ssh s18p1.lan 'pct exec 185020 -- journalctl -u llmrouter -n 50 --no-pager -o cat'
+```
+
+Manuell auffrischen: `POST /auffrischen` mit Admin-Key startet den vollen
+Lauf (Preise neu, Aliasse mit Last-Probe bei Wechsel, `alt/`-Einträge neu).
 
 ## Betrieb