Logging

Zweck: Dokumentiert das Logging-Design, die Datenbank-Tabelle, die Maskierungsregeln und die Anwendung von LogManager.

Kurzüberblick:

• Wir schreiben Logs primär in Dateien (30d Retention) und optional in die DB (logs-Tabelle).
• Payloads werden vor dem Persistieren maskiert (z. B. api_token, password, Authorization).

Schema (Tabelle logs):

• id INT AUTO_INCREMENT PRIMARY KEY
• created_at DATETIME NOT NULL
• job_id INT NULL
• phid VARCHAR(64) NULL -- Phorge PHID, falls vorhanden
• fingerprint VARCHAR(128) NULL
• severity ENUM('debug','info','warning','error','critical') NOT NULL
• channel VARCHAR(64) NOT NULL DEFAULT 'app'
• message TEXT NOT NULL
• payload JSON NULL
• context JSON NULL
• stack_trace TEXT NULL
• host VARCHAR(128) NULL
• app_version VARCHAR(64) NULL
• Indexe: created_at, phid, fingerprint, severity

Migration:

• Datei: sql/create_logs_table.sql (enthält CREATE TABLE und Hinweis zur Retention)
• Ausführen (Beispiel im Dev-Container):

docker compose -f docker-compose.yml -f docker-compose.dev.yml exec -T app \
  php -r 'require "/app/src/Autoloader.php"; $config=require "/app/config/config.php"; $db=new App\\Database\\DBManager($config); $sql=file_get_contents("/app/sql/create_logs_table.sql"); $db->query($sql); echo "created\n";'

Maskierung / Sicherheit:

• Vor Persistenz werden Schlüssel mit Mustern token, password, authorization, api.token, api_token, auth rekursiv ersetzt mit ***REDACTED***.
• File-Logs enthalten maskierte Payloads. DB speichert maskierte JSON im payload-Feld.
• Empfehlung: niemals Secrets unmasked irgendwo im Repo oder Logs speichern.

LogManager (Kurzreferenz):

• Signatur: log(string $message, string $severity = 'info', ?array $payload = null, ?string $fingerprint = null, ?string $phorge_id = null, ?int $job_id = null, string $channel = 'app')
• Behaviour:
  • Maskiert Payloads und schreibt je nach config['log_mode'] in File, DB oder beides (log_dual).
  • app_version wird aus config.php übernommen, host wird automatisch ergänzt.

Konfiguration (in config.php):

• log_mode: file | db | console (default in Vorlage: db)
• log_level: debug | info | warning | error | critical
• log_dual: true/false
• log_dir, log_file (siehe config.template.php)

Beispiele:

require '/app/src/Autoloader.php';
$l = new App\Log\LogManager();
$l->log('Task angelegt', 'info', ['user'=>'alice','api_token'=>'secret-123'], 'fp-123', 'PHID-XYZ', 99, 'maniphest');

Troubleshooting:

• Falls DB-Insert fehlschlägt, schreibt LogManager den Fehler automatisch in die File-Logs (internal Kanal).
• Prüfen: /app/logs/app.log und DB-Tabelle logs.

Nächste Schritte:

• Optional: Background-Job für Retention (DELETE WHERE created_at < NOW() - INTERVAL 30 DAY).
• Integrationstests: Dry-run-Harness ergänzen, um Log-Pfade automatisiert zu prüfen.

---

Ticket-Referenzen: T1019 (Schema), T1022 (LogManager-Implementierung), T1021 (Dokumentation)