Logging
Logging in Ephraim ist für den Produktionsbetrieb gedacht: Störungen erkennen, Ursachen eingrenzen und administrative Eingriffe nachvollziehbar machen. Es ist ausdrücklich nicht dafür gedacht, Prompts, Antworten, Dateien, Tokens oder private Arbeitsverläufe mitzuschreiben.
1. Produktionsprinzip
In Production gilt ein anderes Logging-Modell als in der lokalen Entwicklung. Ephraim zeigt interne PHP-Fehler nicht im Browser an, schreibt keine normale PHP-Fehlerlogdatei als Hauptsignal und meldet kritische App-Probleme über eine begrenzte Admin-Problem-Mail. Die Diagnose beginnt deshalb nicht mit einem großen Rohlog, sondern mit Statusseite, Problem-Mail, Cronmonitor, Runtime-Logs und Super-Admin-Auditberichten.
2. Webserver und Apache
Der produktive Schul-Webserver wird so betrieben, dass Apache kein Diagnosewerkzeug für fachliche HTTP-Anfragen ist. Es gibt kein Apache-Logging von Request-Bodies: keine Formularinhalte, keine Chatnachrichten, keine Datei- oder JSON-Payloads und keine sonstigen Anfrageninhalte. Solche Inhalte werden nicht als Webserverlog benötigt und dürfen dort nicht erscheinen.
Tokens gehören ebenfalls nicht in Apache-Logs. Dazu zählen Session-Cookies, CSRF-Tokens, Reset- und Setzlinks, Cron-Tokens, Bearer-Tokens, Runtime-JWTs, OAuth-Codes und API-Schlüssel. Deshalb ist in Production kein Apache-Accesslog mit Requestzeilen, Query-Strings, Headern oder Cookies als fachliche Diagnosequelle vorgesehen.
3. PHP-App und Problem-Mails
Die PHP-Anwendung behandelt Production-Fehler bewusst zurückhaltend. Interne Details werden nicht an Nutzer ausgegeben. Gefangene Fehlerpfade und globale Fatal- oder Exception-Handler laufen in die Admin-Problem-Mail-Pipeline. Diese Mails sind rate-limitiert, nach Schweregrad filterbar und redigieren offensichtliche Secrets.
| Element | Production-Verhalten |
|---|---|
| Browserausgabe | Keine internen PHP-Fehlerdetails für Nutzer. |
| PHP-Fehlerlog | In Production abgeschaltet; nicht als primäre Betriebsquelle vorgesehen. |
| Admin-Problem-Mail | Redigierter Bericht mit Kontext, Zeit, Schweregrad, Request-Zusammenfassung, IP, User-Agent, Details, Metadaten und gekürztem Trace. |
| Rate-Limit | Gleiche Problemfingerprints werden begrenzt, damit ein Fehler nicht die Mailbox flutet. |
| Redaktion | Tokens, Passwörter, API-Schlüssel, Authorization-Header, lange Hexwerte, Base64-ähnliche Secrets und JWT-ähnliche Werte werden bestmöglich maskiert. |
Die Redaktion ist eine Schutzschicht, keine Einladung zum sorglosen Loggen. Wer eine Fehlermeldung formuliert, schreibt keine Passwörter, DEKs, private Schlüssel, vollständige Prompts, Dateiinhalte oder langen Rohlogs hinein.
4. Spark und KI-Dienste
Die Spark ist die lokale KI-Maschine. Sie verarbeitet Prompts, Kontext, Embeddings, TTS-Anfragen und Runtime-Kommandos für die konkrete Aufgabe. Sie loggt aber keine fachlichen KI- oder TTS-Anfragen: keine KI-Requestpayloads, keine Promptinhalte, keine Modellantworten, keine TTS-Texte, keine TTS-Audiodaten, keine Roh-Tokens, keine Auth-Tokens, keine DEKs und keine Secrets.
Für Retrieval und Vektorerzeugung ruft die Webanwendung den lokalen
SGLang-Embedding-Dienst school-ui-embedding über den konfigurierten
/embeddings-Endpunkt auf. Das betrifft Datei-RAG, Projektmaterial-RAG
und Basiswissen-RAG. Chunk-Auswahl, Rechteprüfung, Entschlüsselung,
Scoreberechnung und Kontextpaket entstehen in Ephraim selbst und werden ebenfalls
nicht als Inhaltslog geführt. Die Spark speichert Embedding-Klartexte, Suchfragen
und Vektor-Payloads im Normalbetrieb nicht dauerhaft.
| Dienst | Was für den Betrieb sichtbar sein darf | Was nicht geloggt wird |
|---|---|---|
| Inference | Technische Metriken wie Anfragezählung, Latenz und Tokenzählungen als Zahlenwerte. | Prompts, Kontexttexte, Modellantworten und Roh-Tokens. |
| Embedding | Technische Verfügbarkeit und Fehlerzustände des konfigurierten Embedding-Endpunkts. | Klartext der zu vektorisierenden Textausschnitte, Suchfragen und Vektor-Payloads. |
| Retrieval in der Webanwendung | Technische Kennzahlen wie Trefferstatus, Größenklasse oder Fehlertyp. | Chunktexte, private Kalenderinhalte, Dateiinhalte und erzeugte Kontextpakete als Log. |
| Runtime und Supervisor | Admin-Aktionen, Jobstatus, Exitcodes, Dienstnamen, Zeitpunkte und technische Meldungen. | Private Chatprompts, Modellantworten, DEKs und Auth-Secrets. |
| TTS | Bereitschaft, Start- und Crashdiagnose des lokalen Sprachdienstes. | Vorzulesender Text, Audiodaten, Access-Logs und Synthese-Metadaten im Normalbetrieb. |
5. Runtime- und Containerlogs
Das Supervisor-Webterminal zeigt für bekannte Runtime-Container einen aktuellen Logauszug
oder verfolgt einen Logstream. Die typischen Befehle entsprechen
docker logs <container> und docker logs -f <container>,
laufen aber über die abgesicherte Runtime-Verbindung und kurzlebige Admin-Tokens.
Diese Logs beantworten Betriebsfragen: Startet ein Dienst? Ist ein Modell bereit? Gibt es Timeouts, Updatefehler, Ressourcenprobleme oder nicht erreichbare interne Dienste? Sie beantworten nicht die Frage, was ein Schüler in einem privaten Chat geschrieben hat.
6. Cron-Logs und Wartung
Cron besitzt eine eigene adminlesbare Logspur für den letzten Wartungslauf. Sie zeigt Start, Ende, betroffene Aufgaben, Fehler und Kennzahlen. Zusätzlich speichert Ephraim eine Zusammenfassung pro Task. Fehlschläge einzelner Tasks werden als Problem gemeldet, ohne den gesamten Lauf sofort abzubrechen.
Cron-Logging ist bewusst kein langfristiges Vollarchiv. Es soll beantworten, ob Wartung läuft, ob sie zuletzt erfolgreich war und welche Aufgabe zuletzt auffällig war. Für Details zu Ausführungsarten, Token/IP-Schutz und Datenschutzgrenzen siehe Cron.
7. Audit, Sicherheitsereignisse und Grenzen
Neben Logs gibt es Audit- und Sicherheitsereignisse. Datei-Sicherheitsereignisse dokumentieren blockierte oder auffällige Uploads mit technischer Begründung. Super-Admin- Auditberichte verdichten Runtime- und Sitzungsdaten zu Markdown-Berichten. Sie dienen der Systemprüfung und nicht dem Öffnen privater Chats.
Roh-Exports bleiben ein Super-Admin-Werkzeug. KI-Auditberichte werden vor der Auswertung und Speicherung zusätzlich bereinigt: Bearer-Tokens, benannte Secret-Felder, lange Tokenstrings, URLs und private Schlüssel werden maskiert. Trotzdem gilt: Ein Auditbericht ist ein sensitives Betriebsdokument. Er gehört nicht in öffentliche Tickets, nicht in normale Chatverläufe und nicht in ungeschützte Cloudordner.
8. Was nicht in Logs gehört
Ephraim folgt bei Logging einem Minimalprinzip. Wenn eine Information nicht nötig ist, wird sie nicht protokolliert. Wenn eine Information für Diagnose nötig ist, wird sie so weit reduziert, dass sie den Betrieb erklärt, aber private Inhalte schützt.
| Nicht loggen | Stattdessen verwenden |
|---|---|
| Passwörter, Resetlinks, Setzlinks, CSRF-Tokens, Session-Cookies, Bearer-Tokens, OAuth-Codes, Runtime-JWTs. | Tokenart, Zeitpunkt, Endpunkt und redigierte Fehlerklasse. |
| User-DEKs, Server-Schlüssel, private Schlüssel, API-Keys und vollständige Connection-Strings. | Konfigurationsbereich, Dienstname und Hinweis „Secret fehlt“, „Secret ungültig“ oder „Signaturprüfung fehlgeschlagen“. |
| Prompts, Chatantworten, private Dateien, Projektdateien, Kalenderinhalte, Erinnerungen und private Wissensquellen. | Interne ID, Dateityp, Größenklasse, Job-ID, Chunkanzahl oder Status. |
| Lange Rohlogs, vollständige Stacktraces in Tickets, komplette Audit-Exports. | Kleiner relevanter Ausschnitt, Fehlerfingerprint, Zeitfenster und betroffener Dienst. |
9. Ablauf bei einer Produktionsstörung
- Statusseite prüfen: Webserver, Spark, Inference, Runtime und Containerzustände einordnen.
- Prüfen, ob eine Admin-Problem-Mail zum Zeitpunkt der Störung eingegangen ist.
- Bei Wartungsproblemen Cronstatus, letzten Erfolg, Tasktabelle und letztes Cron-Log lesen.
- Bei Spark-Problemen gezielt Runtime- oder Containerlogs für den betroffenen Dienst öffnen.
- Bei Sicherheits- oder Updatefragen Super-Admin-Auditberichte und Datei-Sicherheitsereignisse heranziehen.
- Nur die kleinste nötige technische Information weitergeben; Tokens, private Inhalte und Rohdumps redigieren.
- Nach der Korrektur erneut Status, Cron und betroffenen Dienst prüfen.
10. Abgrenzung
Logging ersetzt keine Datensicherung, kein Patchmanagement, keine Zugriffsprüfung und keine pädagogische Bewertung. Logs zeigen technische Ereignisse. Sie erklären nicht automatisch fachliche Ursachen und sie berechtigen nicht dazu, private Lernarbeit zu lesen.
Die konkrete Aufbewahrung von Spark-SSH-Adminlogs, Supervisor-Logs, Containerlogs und Auditberichten ist Teil des organisatorischen Betriebskonzepts. Ephraim liefert dafür reduzierte technische Spuren und Redaktionsmechanismen; die Schule legt Zugriff, Retention und Verantwortlichkeiten im Produktionsbetrieb verbindlich fest.