Loglevel einstellen
In manchen Fällen ist die Ursache eines Problems im Standard Loglevel nicht zu erkennen; hier kann das Loglevel entsprechend eingestellt und der Informationen-Output erhöht werden.
Das Loglevel kann über die application.yml, die Web API oder das System-Portal gesetzt werden. Der Weg über die Web API wirkt sofort, benötigt keinen Neustart und keine zusätzliche Freischaltung und ist daher der empfohlene Weg im laufenden Betrieb. Für das System-Portal ist seit Relution 26.4 eine einmalige Freischaltung des zugehörigen Actuator-Endpoints erforderlich.
Speicherort der Log-Dateien
Wo sich die Protokolldateien für Docker, Linux und Windows befinden, ist unter Relution Logs → beschrieben.
Aktivierung des System-Portals
Diesen Abschnitt in der application.yml im Relution-Verzeichnis hinzufügen:
relution:
spring-boot-admin:
enabled: true
Die Änderung wird erst nach einem Neustart des Relution-Servers wirksam. Anschließend erscheint für System-Administratoren der Eintrag System Portal im Support-Menü (Fragezeichen-Symbol in der Kopfleiste).
Freischaltung der Actuator-Endpoints
Seit Relution 26.4 stellt Relution aus Sicherheitsgründen standardmäßig nur den Health-Endpoint bereit. Im System-Portal ist deshalb zunächst ausschließlich der Bereich Details sichtbar. Der Bereich Logger erscheint erst, nachdem der zugehörige Endpoint in der application.yml des Relution-Servers freigeschaltet wurde:
management:
endpoints:
web:
exposure:
include:
- health
- loggers
Die Liste ersetzt die Standardkonfiguration vollständig. health muss darin enthalten bleiben, da andernfalls der Health-Endpoint entfällt und damit auch die Statusanzeige des System-Portals sowie die Health-Prüfungen von Loadbalancern und Cluster-Knoten.
Nach der Anpassung ist ein Neustart des Relution-Servers erforderlich, damit die Änderung wirksam wird.
Weitere Bereiche des System-Portals lassen sich nach demselben Muster einzeln ergänzen:
| Bereich im System-Portal | Endpoint |
|---|---|
| Logger | loggers |
| Umgebungskonfiguration | env |
| Metriken | metrics |
| Thread-Dump | threaddump |
| Caches | caches |
| Geplante Tasks | scheduledtasks |
| Mappings | mappings |
| Configuration Properties | configprops |
| Log | logfile |
| Quartz | quartz |
Das System-Portal zeigt die Bezeichnungen der Bereiche in der Sprache des Browsers an; in einem englischsprachigen Browser erscheinen die englischen Bezeichnungen.
Aktivierung des DEBUG Logs im System-Portal
Voraussetzung sind ein aktiviertes System-Portal sowie ein freigeschalteter loggers-Endpoint, siehe die beiden vorangehenden Abschnitte.
In Relution als System-Administrator anmelden. Der Standard-Benutzername ist
admin.Im Support-Menü (Fragezeichen-Symbol) System Portal öffnen.

Anschließend die Anwendung aufklappen und über Instanzdetails öffnen die zugehörige Instanz aufrufen.

In den Bereich Logger wechseln.

Die Suche nutzen, um die entsprechenden
LoggeraufDEBUGzu stellen.ROOTaktiviert sämtlicheLoggerund ist daher nur in Ausnahmefällen zu nutzen, da schnell viel Inhalt generiert wird. Im Beispiel ist dieAppleMdmResourceaktiviert worden.
Die Einstellung ist direkt aktiv, ohne dass Dienste neu gestartet werden müssen.
Beim Neustart des Relution-Dienstes oder des Docker-Containers wird das Log wieder zurück auf INFO gestellt.
DEBUG-Log auch über einen Neustart hinaus aktiv lassen
Da das DEBUG-Log nach einem Neustart der Instanz wieder auf INFO zurück gestellt wird, ist es auf dem oben beschrieben Weg nicht möglich, initiale Fehler beim Startvorgang, z.B. im Kontext einer LDAP-Anbindung, zu loggen. Hierfür gibt es die Möglichkeit, das Log in der application.yml zu definieren. Diese wird direkt beim Start geladen und aktiviert somit das DEBUG-Log.
Die folgenden Einträge werden ohne Einrückung, also ab der ersten Spalte, in die application.yml eingefügt. Die Änderung wird nach einem Neustart des Relution-Servers wirksam.
Es wird empfohlen, einen oder mehrere Logs individuell und zielgerichtet zu aktivieren. Dazu werden die einzelnen Logger untereinander in die Datei eingefügt.
Mehrere individuelle Logs
logging.level.io.relution.security.ldap: DEBUG
logging.level.io.relution.apple.mdm.AppleMdmResource: DEBUG
Im Beispiel wären jetzt die LDAP-Funktionalität und die AppleMdmResource im DEBUG-Log aktiviert.
Die Bezeichnungen der Logger sind im System-Portal einsehbar, sofern der loggers-Endpoint freigeschaltet ist; andernfalls entsprechen sie dem Paket- beziehungsweise Klassennamen aus dem Log.
Der folgende Eintrag aktiviert DEBUG für das Paket io.relution, also nahezu den gesamten Relution-Code, jedoch ohne Fremdbibliotheken wie das LDAP-SDK oder EclipseLink:
logging.level.io.relution: DEBUG
ROOT auf DEBUG setzen
ROOT-Ebene kann unter Umständen schnell viel Inhalt generiert werden. Diese Funktionalität sollte nur in absoluten Ausnahmefällen für kurze Analysetätigkeiten genutzt werden. Bereits bei kleineren Installationen kann es hier zu erheblichen Performance-Einbußen kommen.Der ROOT-Logger umfasst sämtliche Logger einschließlich der Fremdbibliotheken:
logging.level.root: DEBUG
Setup Loglevel mit einem Logging User über die Web API
Es besteht die Möglichkeit, auf der System-Organisation einen speziellen Logging-User zu erstellen, der das Loglevel über die Web API komfortabel ändern kann. Dies erspart das manuelle Bearbeiten der YAML-Konfigurationsdatei sowie einen Neustart des Servers.
Dieser Weg setzt weder ein aktiviertes System-Portal noch eine Freischaltung von Actuator-Endpoints voraus und ist deshalb der empfohlene Weg, um Log-Level im laufenden Betrieb zu ändern. Wie im System-Portal gilt auch hier: Nach einem Neustart der Instanz sind die gesetzten Log-Level wieder auf ihren Ausgangswert zurückgesetzt.
1. Berechtigung und Benutzer erstellen
Um den Logging-User zu erstellen, muss zunächst auf der System-Organisation eine neue Berechtigung erstellt werden,
bei der unter System → Logging konfigurieren die Berechtigung aktiviert und gespeichert wird.
Anschließend kann ein neuer Benutzer ausschließlich für den Logging-Access erstellt werden, dem die zuvor erstellte Berechtigung zugewiesen wird.
Hinweis: Der System-Administrator verfügt standardmäßig über diese Berechtigung.


2. Access Token erstellen
Für diesen neuen Benutzer kann ein Access Token erstellt werden, um die Handhabung zu erleichtern. Hierzu muss sich der Benutzer zunächst anmelden und über das Benutzerprofil den Token erstellen. Im Dialog bleibt unter API-Bereiche der Standardwert Management-Portal ausgewählt, da der Logging-Endpoint zu diesem Bereich gehört; ein Token ohne diesen Bereich wird vom Endpoint abgewiesen. Der Access Token wird nur einmalig angezeigt, ein weiterer Token kann bei Bedarf erstellt werden.


3. Steuerung des Loglevels über die Web API
Um das Loglevel über die Web API zu steuern, wird in der System-Organisation über das Support-Menü (Fragezeichen-Symbol in der Kopfleiste) der Eintrag Web API geöffnet; die Web API erscheint in einem neuen Tab. Dort öffnet Authorize den Anmeldedialog für den Logging-User.
Hier kann der Access Token des Logging-Users verwendet werden, um den Zugriff zu erleichtern und die Authentifizierung beim Curl automatisch hinzuzufügen.
Im Punkt userAccessTokenAuth muss der Token eingefügt und autorisiert werden.
Hinweis: Alternativ kann die Anmeldung als System-Administrator der System-Organisation erfolgen; die Eingabe des Tokens entfällt dann.
Beim Punkt logging können die benötigten Logging-Punkte sowie das Loglevel definiert und ausgeführt werden. Der Endpoint lautet /api/management/v1/system/logging. Im Feld packageNames lassen sich mehrere Paket- oder Klassennamen in einem Aufruf angeben, außerdem Spring-Log-Gruppen wie web oder sql:
{
"packageNames": ["io.relution.security.ldap", "io.relution.apple.mdm.AppleMdmResource"],
"logLevel": "DEBUG"
}
Eine erfolgreiche Ausführung wird mit dem Code 204 bestätigt, und der ausgeführte Curl-Befehl wird angezeigt. In einer Cluster-Installation gelten die über die Web API gesetzten Log-Level automatisch auf allen Knoten. Änderungen, Reset und Restore werden im Audit-Log protokolliert.




Zusätzlich besteht die Möglichkeit, das Logging auf die Standard-Einstellungen zurückzusetzen. Ein Reset (/reset) erwartet eine Liste von Paket- oder Gruppennamen und setzt nur diese zurück; ein Restore (/restore) setzt alle über die Web API geänderten Logger zurück.

4. Steuerung des Loglevels über den Curl Befehl
Es besteht auch die Möglichkeit, das Loglevel über den Curl-Befehl zu steuern, indem der über die Web API generierte Curl als Alias oder Skript für die zukünftige Verwendung gespeichert wird.

5. Verwendung für Support-Mitarbeiter oder andere Mitarbeiter
Um einem Benutzer, beispielsweise einem Relution-Support-Mitarbeiter, Zugriff zu gewähren, genügt es, entweder den Token weiterzugeben oder die E-Mail-Adresse des Logging-Benutzers, die mit einer gültigen Relution-Instanz verknüpft ist, dem Relution-Support-Team mitzuteilen.
Secure Mail Gateway
Das Secure Mail Gateway läuft als eigener Container. Die hier beschriebenen Wege (Web API, System-Portal, application.yml des Relution-Servers) wirken nicht auf das SMG. Sein Loglevel wird in der application.yaml des SMG-Containers gesetzt, die Protokolle zeigt docker logs smg. Die Anleitung steht unter Secure Mail Gateway installieren →.