Logging & License-Cache

Der AgiqonConnector schreibt strukturierte Log-Einträge in dedizierte Dateien und reduziert Live-HTTP-Calls an die License-API durch einen integrierten Cache.

---

Log-Kanäle und Logdateien

Ab Version 3.7.2 verwendet der Connector vier dedizierte Monolog-Kanäle. Jeder Kanal schreibt in eine eigene rotierende Logdatei unter log/AgiqonConnector/:

Kanal	Datei	Inhalt
agiqon_api	api_<env>.log	Alle HTTP-Calls an die License-API
agiqon_oci	oci_<env>.log	OCI-Login-Controller und Funktions-Controller
agiqon_cxml	cxml_<env>.log	cXML-Login-Controller und cXML-Auth-Controller
agiqon_connector	connector_<env>.log	Allgemeine Connector-Events

<env> entspricht dem Symfony-Umgebungswert (dev, prod, …).

Rotationseinstellungen: Jede Datei rotiert automatisch. Es werden maximal 14 Dateien auf DEBUG-Level gespeichert.

---

Was wird geloggt?

OCI-Login-Controller (agiqon_oci)

Ereignis	Level
Erfolgreicher Login	INFO
Falsche Zugangsdaten	WARNING
Inaktives System	WARNING
Fehlende Pflichtfelder	WARNING
Ungültige Hook-URL	WARNING
Ungültige Lizenz	WARNING
Nicht unterstützte OCI-Funktion (OciUndefinedFunctionController)	WARNING
Unbehandelter Fehler im Download-JSON-Ablauf	ERROR

cXML-Login-Controller und cXML-Auth-Controller (agiqon_cxml)

Ereignis	Level
Erfolgreicher Login / Auth	INFO
Ungültiger oder abgelaufener Auth-Key	WARNING
Kunde nicht gefunden	WARNING
System nicht gefunden	WARNING
Fehlerhaft gespeichertes XML	WARNING
SimpleXML-Parse-Fehler	WARNING

License-API-Client (agiqon_api)

Ereignis	Level
Cache-Hit (Lizenz aus Cache bedient)	DEBUG
Lizenzprüfung live gegen API	DEBUG
Stale-Cache verwendet (API nicht erreichbar)	WARNING

---

License-Check-Caching

Um die Anzahl der Live-HTTP-Calls an die License-API bei jedem Login zu reduzieren, cached der Connector das Ergebnis der Lizenzprüfung.

Funktionsweise

Login-Request
     │
     ▼
Cache-Lookup (cache.app, Schlüssel: agiqon_connector.license.<type>.<hash>)
     │
     ├── Cache-Hit?  → Ergebnis direkt zurückgeben (kein API-Call)
     │
     └── Cache-Miss?
              │
              ▼
         HTTP-Call an License-API
              │
              ├── Erfolg (2xx)
              │      → Ergebnis in Kurz-Cache (10 min) speichern
              │      → Ergebnis in Stale-Cache (24 h) speichern
              │      → Ergebnis zurückgeben
              │
              ├── 4xx (ungültige Lizenz)
              │      → Kurz-Cache + Stale-Cache invalidieren
              │      → LicenseValidationException werfen
              │
              └── Netzwerkfehler / API nicht erreichbar
                     │
                     ├── Stale-Cache vorhanden?
                     │      → Stale-Ergebnis zurückgeben (WARNING geloggt)
                     └── Kein Stale-Cache
                            → LicenseApiUnavailableException werfen

Cache-Parameter

Parameter	Wert
Cache-Service	cache.app (Symfony)
Gültigkeitsdauer	10 Minuten (600 Sekunden)
Stale-Fallback-Dauer	24 Stunden (86 400 Sekunden)
Cache-Schlüsselformat	agiqon_connector.license.<type>.<sha1(id.domain)>

Cache-Invalidierung

Der Cache wird sofort invalidiert, wenn die License-API eine 401- oder 403-Antwort zurückgibt. Ungültige Lizenzen werden dadurch nie aus dem Cache bedient.

Hinweis für den Betrieb

Der Stale-Fallback stellt sicher, dass bereits eingeloggte und frisch eingeloggte Nutzer bei einem vorübergehenden Ausfall der License-API weiterarbeiten können. Nach spätestens 24 Stunden wird ohne gültige API-Antwort kein Login mehr möglich sein.

---

Exception-Klassen

Ab Version 3.7.2 gibt es typisierte Exception-Klassen für License-API-Fehler:

Klasse	Wann geworfen
LicenseValidationException	4xx-Antwort der License-API (trägt den HTTP-Statuscode)
LicenseApiUnavailableException	Netzwerkfehler / License-API nicht erreichbar
OciAuthenticationException	Fehlgeschlagene OCI-Authentifizierung