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. Nutzer-DEKs gehören nicht in eine dauerhafte Speicherung oder ein Backendprotokoll.
Für Retrieval und Vektorerzeugung ruft die Webanwendung den lokalen Embedding-Dienst 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 | Adminidentität, Rolle, Aktionen, Jobstatus, Exitcodes, Dienstnamen und Zeitpunkte. | Private Chatprompts, Modellantworten, DEKs und Auth-Secrets. |
| Broker und Observer | Reduzierte Zustände und begrenzte Logstreams ausschließlich für bekannte Spark-Container. | Schreibzugriffe, Container-Exec, allgemeine Docker-Operationen und Ausgabe von Loginhalten in eigenen Logs. |
| 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.
Die Runtime und der Observer besitzen keinen Docker-Socket. Die Runtime fordert
freigegebene Zustände und begrenzte Logstreams beim Observer an. Dieser nutzt den
festen Broker. Beide Verbindungen bleiben auf interne Unix-Sockets beschränkt.
Nur der Broker besitzt in diesem Diagnosepfad den privilegierten Dockerzugriff.
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.
Der Container school-ui-logrotate ist selbst Teil des Runtime-Snapshots und wird auf der Statusseite über seinen Docker-Zustand angezeigt. Er prüft stündlich, ob technische Aktionsprotokolle rotiert werden müssen. Die Dateien werden täglich rotiert, komprimiert und mit 30 Rotationen vorgehalten.
Auch school-ui-observer erscheint als eigener Container im Status-Snapshot. Er hat keinen Netzwerkport und stellt weder Start, Stop, Exec noch allgemeine Docker-Abfragen bereit. Der Broker prüft feste Containernamen und liefert nur freigegebene Zustände oder begrenzte Logs. Ein lesend eingebundener Docker-Socket ist allein keine Zugriffssperre für die Dockerverwaltung. Der privilegierte Broker bleibt deshalb ein besonders geschützter Teil des Betriebs.
| Technische Logart | Durchgesetzte Grenze |
|---|---|
| Runtime-Aktionsprotokolle | täglich, 30 Rotationen |
| Abgeschlossene oder fehlgeschlagene Supervisor-Jobs und Joblogs | 90 Tage seit der jüngsten Dateiänderung, soweit die Daten nicht für Current, Previous oder eine sichere Wiederherstellung gebunden bleiben. |
| Docker-Stdout je Spark-Container einschließlich Observer und Logrotate | fünf Dateien zu je 10 MiB, also ungefähr 50 MiB |
| Aktive oder wiederaufnehmbare Supervisor-Jobs | keine automatische Alterslöschung |
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.
Archivabrufe bleiben ein Super-Admin-Werkzeug. Der authentifizierte Sitzungsabruf liefert begrenzte Metadaten und redigierte Vorschauen, keinen vollständigen Rohmitschnitt. Der echte Abruf über sieben Tage wurde mit zwei interaktiven Sitzungen samt Timing und einem rotierten Dateipaar geprüft. 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.
Für Runtime-Aktionslogs, Supervisor-Jobs und Docker-Stdout setzt Ephraim die oben genannten technischen Grenzen durch. Interaktive SSH-Sitzungen werden im gesonderten Sitzungsarchiv mit zugehörigen Timingdateien und geregelter Rotation geführt. Neue nichtinteraktive SSH-Kommandos werden nicht aufgezeichnet, der frühere Commandlogger ist deaktiviert. Als Aufbewahrungsziel sind 365 Tage vorgesehen. Eine automatische Alterslöschung setzt eine verlässlich geprüfte Uhr voraus und ist im aktuellen Profil deaktiviert. Zugriff und Weitergabe bleiben Teil des organisatorischen Betriebskonzepts. Runtime-Aktionsprotokolle und SSH-Aufnahmen können personenbezogene Betriebsdaten enthalten, etwa Adminidentität, Verbindungsmetadaten oder Terminalausgaben. Sie sind von privaten Lernchats und vom normalen Kontodatenexport getrennt. Die Schule legt Verantwortlichkeiten und berechtigte Zugriffe verbindlich fest.