Monolog-Logging (zmsslim)
ZMS-Anwendungen nutzen einen gemeinsamen PSR-3-Logger auf der globalen App-Klasse: App::$log. Konfiguriert wird er in zmsslim durch BO\Slim\Bootstrap und von allen Slim-Modulen (zmsapi, zmsadmin, zmscitizenapi, …) geteilt.
Das Mindest-Log-Level wird ebenfalls in zmsslim zentral gesetzt: DEBUGLEVEL in der Umgebung → ZMS_DEBUGLEVEL in zmsslim → App::DEBUGLEVEL in jedem Modul für Bootstrap::configureLogger().
Kurzreferenz
| Thema | Detail |
|---|---|
| Logger-Property | App::$log (Monolog\Logger, vor Bootstrap null) |
| Umgebungsvariable | DEBUGLEVEL (z. B. in .env, DDEV, Deployment) — Standard INFO |
| zmsslim-Define | ZMS_DEBUGLEVEL — in Application.php aus getenv('DEBUGLEVEL') gesetzt |
| App-Konstante | App::DEBUGLEVEL — jedes Modul erbt ZMS_DEBUGLEVEL von \BO\Slim\Application |
| Effektives Mindest-Level | Was nach dem Bootstrap gilt (App::DEBUGLEVEL zur Laufzeit) |
| Web-Bootstrap | \BO\Slim\Bootstrap::init() |
| CLI / Cron | \BO\Slim\Bootstrap::ensureLogger() oder initForCli() über script_bootstrap.php |
| Ausgabe | JSON-Zeilen auf stderr (Web) oder stdout (CLI/Cron) |
| Nicht verwenden | PHP error_log(), print_r(), echo für Anwendungs-Logs |
Zentrales Debug-Level (ZMS_DEBUGLEVEL)
zmsslim steuert das Debug-Level für alle Slim-Module. In Produktion gibt es kein separates Log-Level pro Modul; eine Umgebungsvariable gilt überall, wo über \BO\Slim\Bootstrap gebootstrapped wird.
flowchart LR env["DEBUGLEVEL Env"] zms["ZMS_DEBUGLEVEL\n(zmsslim Application.php)"] app["App::DEBUGLEVEL\n(jedes Modul App)"] boot["Bootstrap::configureLogger()"] mono["Monolog-Mindest-Level\n(App::$log)"] env --> zms --> app --> boot --> mono
- Betrieb setzt
DEBUGLEVEL(z. B.INFOoderWARNING) in.env, DDEV oder Deployment. - Beim Laden von
zmsslim/src/Slim/Application.phpwirdZMS_DEBUGLEVELaus dieser Env-Variable definiert (StandardINFO, falls nicht gesetzt). \BO\Slim\Applicationdeklariertconst DEBUGLEVEL = ZMS_DEBUGLEVEL. Jedes Modul mitclass App extends \BO\Zmsapi\Application(usw.) erbt dieselbe Konstante, sofern nicht lokal überschrieben.- Beim Bootstrap rufen
Bootstrap::init()/ensureLogger()/initForCli()configureLogger(App::DEBUGLEVEL, App::IDENTIFIER)auf. Das Level ist gemeinsam; in den JSON-Logs unterscheiden sich nurApp::IDENTIFIERundApp::MODULE_NAMEpro Modul.
ZMS_DEBUGLEVEL ist damit die zentrale zmsslim-Vorgabe, wie ausführlich zmsapi, zmsadmin, zmscitizenapi, zmsmessaging, Cron-Skripte und die anderen Slim-Apps loggen.
Konfiguration: DEBUGLEVEL in der Umgebung (kein separates Env ZMS_DEBUGLEVEL).
Zur Laufzeit im Code: App::DEBUGLEVEL (basierend auf ZMS_DEBUGLEVEL).
Seltene Ausnahme: const DEBUGLEVEL = 'WARNING'; in einem Modul-config.php nur für lokale Tests — nicht in gemeinsamen Deployment-Configs.
CLI-Fallback: ist App::DEBUGLEVEL noch nicht definiert, liest Bootstrap::initForCli() direkt getenv('DEBUGLEVEL').
Log-Level
App::DEBUGLEVEL (aus ZMS_DEBUGLEVEL) legt das Mindest-Level für Monolog fest. Nachrichten darunter werden verworfen.
DEBUGLEVEL Env / Konstante | Monolog-Konstante | Typische Nutzung in ZMS |
|---|---|---|
DEBUG | Logger::DEBUG | Ausführliche Diagnose (Mail-Payloads, Cache) |
INFO | Logger::INFO | Normaler Betrieb (Login, Cron-Fortschritt, Cache-Treffer) |
NOTICE | Logger::NOTICE | Beachtenswert, aber erwartbar |
WARNING | Logger::WARNING | Behebbare Probleme (Rate Limits, übersprungene Entitäten) |
ERROR | Logger::ERROR | Fehler mit Handlungsbedarf |
CRITICAL | Logger::CRITICAL | Schwere Fehler (z. B. Twig-Exception-Handler) |
ALERT | Logger::ALERT | Selten; Monolog-Skala |
EMERGENCY | Logger::EMERGENCY | Selten; Monolog-Skala |
Die Zuordnung steht in zmsslim/src/Slim/Bootstrap.php ($debuglevels, parseDebugLevel()).
Beispiel-Konfiguration
# .env / DDEV / Deployment — gilt für alle Slim-Module über zmsslim
DEBUGLEVEL=INFODefinition in zmsslim/src/Slim/Application.php:
define('ZMS_DEBUGLEVEL', getenv('DEBUGLEVEL') ? getenv('DEBUGLEVEL') : 'INFO');
const DEBUGLEVEL = ZMS_DEBUGLEVEL;Ungültige Werte fallen in Bootstrap::parseDebugLevel() auf DEBUG zurück.
HTTP-Request-Logging pro Modul
Anders als DEBUGLEVEL (ein Wert für alle Slim-Module) wird HTTP-Request-/Response-Logging pro Modul über ZMS_<MODUL>_LOGGER_*-Umgebungsvariablen konfiguriert — dasselbe Namensschema wie ZMS_ADMIN_TWIG_CACHE, ZMS_API_TWIG_CACHE usw.
Module mit RequestLoggingMiddleware (über BO\Slim\Helper\ModuleLoggerInitializer oder eigenes Bootstrap) schreiben pro verarbeitetem Request eine strukturierte HTTP Request-Zeile über BO\Slim\LoggerService::logRequest() → App::$log.
Nur Request-Log-Drosselung
…_LOGGER_MAX_REQUESTS und …_LOGGER_MAX_ERROR_REQUESTS sind Access-Log-Drosseln. Sie begrenzen, wie viele HTTP Request-Zeilen LoggerService::logRequest() pro Zeitfenster schreibt. Sie begrenzen kein allgemeines Anwendungs-Logging.
| Logging-Pfad | Durch LOGGER_MAX_* gedrosselt? | Gesteuert über |
|---|---|---|
HTTP Request (Status < 400) | Ja — …_LOGGER_MAX_REQUESTS | Env pro Modul + …_LOGGER_CACHE_TTL |
HTTP Request (Status ≥ 400) | Nur wenn …_LOGGER_MAX_ERROR_REQUESTS > 0 | Env pro Modul (Standard 0 = unbegrenzt) |
LoggerService::logError() (Exceptions) | Nein | — |
LoggerService::logWarning() / logInfo() | Nein | — |
Direkte App::$log->info() / warning() / error() im App-Code | Nein | DEBUGLEVEL |
Kurz: DEBUGLEVEL steuert global die Ausführlichkeit von Anwendungs-Logs; LOGGER_MAX_* verhindert nur, dass hochfrequente Module (v. a. Calldisplay und Ticketdrucker) den Log mit routinemäßigen erfolgreichen Requests überfluten.
Erfolgreiche und fehlgeschlagene Request-Logs nutzen getrennte Zähler und dieselbe Fensterlänge (…_LOGGER_CACHE_TTL, Standard 60 Sekunden). Eine gedrosselte erfolgreiche Poll-Antwort blockiert nicht das spätere Loggen eines 500ers desselben Moduls.
| Modul | Env-Präfix | Typischer Traffic |
|---|---|---|
| zmscitizenapi | ZMS_CITIZENAPI_LOGGER_* | Öffentliche Buchungs-API |
| zmsapi | ZMS_API_LOGGER_* | Interne REST-API |
| zmsadmin | ZMS_ADMIN_LOGGER_* | Mitarbeiter-UI |
| zmscalldisplay | ZMS_CALLDISPLAY_LOGGER_* | Aufrufmonitore (häufiges Polling) |
| zmsstatistic | ZMS_STATISTIC_LOGGER_* | Statistik-UI |
| zmsticketprinter | ZMS_TICKETPRINTER_LOGGER_* | Ticketdrucker (häufiges Polling) |
LoggerService-Variablen
| Variable | Standard | Rolle |
|---|---|---|
…_LOGGER_MAX_REQUESTS | 1000 | Max. erfolgreiche HTTP Request-Zeilen (Status < 400) pro Rate-Limit-Fenster (CACHE_TTL) |
…_LOGGER_MAX_ERROR_REQUESTS | 0 | Max. fehlgeschlagene HTTP Request-Zeilen (Status ≥ 400) pro Fenster; 0 = unbegrenzt |
…_LOGGER_RESPONSE_LENGTH | 1048576 | Max. Response-Body-Bytes bei Fehler-Logs |
…_LOGGER_STACK_LINES | 20 | Stacktrace-Zeilen bei geloggten Exceptions |
…_LOGGER_MESSAGE_SIZE | 8192 | Max. Größe einer einzelnen Log-Nachricht |
…_LOGGER_CACHE_TTL | 60 | Rate-Limit-Fenster in Sekunden (nutzt CACHE_DIR) |
…_LOGGER_MAX_RETRIES | 3 | Cache-Lock-Wiederholungen für Rate Limiting |
…_LOGGER_BACKOFF_MIN / …_LOGGER_BACKOFF_MAX | 100 / 1000 | Backoff zwischen Wiederholungen (ms) |
…_LOGGER_LOCK_TIMEOUT | 5 | Cache-Lock-Timeout (Sekunden) |
Vollständige Beispiele stehen in .ddev/.env.template bzw. .devcontainer/.env.template.
Feinabstimmung bei hoher Request-Frequenz
zmscalldisplay und zmsticketprinter sind Besonderheiten: Jeder Monitor bzw. Ticketdrucker pollt typischerweise alle paar Sekunden den Server. Mit Standard LOGGER_MAX_REQUESTS=1000 erzeugen schon wenige Geräte viel repetitive Log-Menge — auch bei DEBUGLEVEL=INFO.
Für diese Module empfiehlt sich ein niedrigerer Wert für ZMS_CALLDISPLAY_LOGGER_MAX_REQUESTS und/oder ZMS_TICKETPRINTER_LOGGER_MAX_REQUESTS, damit Routine-Polls den Logstrom nicht dominieren. Admin-, API- und Citizen-Module können meist bei den Defaults bleiben.
# Beispiel: Poll-Logging für Display/Drucker begrenzen, andere Module unverändert
ZMS_CALLDISPLAY_LOGGER_MAX_REQUESTS=120
ZMS_TICKETPRINTER_LOGGER_MAX_REQUESTS=120
# Andere Module weiterhin mit Template-Default (1000)
ZMS_ADMIN_LOGGER_MAX_REQUESTS=1000
ZMS_API_LOGGER_MAX_REQUESTS=1000Ein niedrigeres …_LOGGER_MAX_REQUESTS drosselt nur erfolgreiche HTTP Request-Zeilen (Monolog info, Status < 400). Fehlgeschlagene Requests (Status ≥ 400, Monolog error) nutzen …_LOGGER_MAX_ERROR_REQUESTS; Standard 0 bedeutet kein Limit.
Diese Variablen betreffen keine Exceptions, Warnungen oder Info-Meldungen aus anderen LoggerService-Methoden und keine direkten App::$log->…-Aufrufe im restlichen Code.
Logging im Code
Nach bootstrap.php oder script_bootstrap.php:
\App::$log->info('Login successful', ['account' => $accountName]);
\App::$log->warning('Could not remove availability', ['availabilityId' => $id]);
\App::$log->error('SQL import failed', ['exception' => $e->getMessage()]);PSR-3-Methoden in Kleinbuchstaben: debug, info, notice, warning, error, critical, alert, emergency.
Kontext-Arrays
Strukturierten Kontext (zweites Argument) bevorzugen. Zusätzliche Felder u. a.: application, module, bei Cron cron / cron_name (ZMS_CRON_LOG, ZMS_CRON_NAME).
Bibliotheken ohne Bootstrap
Optional nur mit Prüfung:
if (class_exists('\App', false) && isset(\App::$log)) {
\App::$log->error('…', ['context' => $value]);
}Log-Inventar im Repository
Die folgende Tabelle wird automatisch aus App::$log->… in Modul-PHP-Quellen erzeugt (ohne vendor/ und tests/). Lokal aktualisieren:
cd docs && npm run docs:log-inventoryAktualisierung auch bei npm run docs:dev / docs:build. Nutze die Filter, die Suche oder Klick auf eine Spaltenüberschrift zum Sortieren (auf-/absteigend umschalten).
Showing 185 of 185 entries · sorted by module (asc)
Verwandtes
- Monitoring und Status —
GET /status/-Metriken und Grafana
Verwandter Code
zmsslim/src/Slim/Application.php—ZMS_DEBUGLEVEL,DEBUGLEVEL,public static $logzmsslim/src/Slim/Bootstrap.php— Logger-Konfigurationzmsslim/src/Slim/LoggerService.php— HTTP-Request-Logging, Rate Limitingzmsslim/src/Slim/Helper/ModuleLoggerInitializer.php— Logger-Env und Middleware pro Modulzmsslim/README.md— Slim-Bootstrap-Übersicht