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.

Das Log-Level DEBUG sollte dabei nur zu Analysezwecken verwendet werden, da deutlich mehr Informationen ins Log geschrieben werden und dieses entsprechend stärker anwächst. Nach Abschluss der Analyse ist das Log-Level wieder auf INFO zurückzusetzen.

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).

Unbedingt auf die Einrückung der einzelnen Zeilen achten (zwei Leerzeichen je Ebene). Es empfiehlt sich, das System-Portal nach Beenden der Arbeiten wieder zu deaktivieren.

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-PortalEndpoint
Loggerloggers
Umgebungskonfigurationenv
Metrikenmetrics
Thread-Dumpthreaddump
Cachescaches
Geplante Tasksscheduledtasks
Mappingsmappings
Configuration Propertiesconfigprops
Loglogfile
Quartzquartz

Das System-Portal zeigt die Bezeichnungen der Bereiche in der Sprache des Browsers an; in einem englischsprachigen Browser erscheinen die englischen Bezeichnungen.

Die Actuator-Endpoints werden auf dem Management-Port 8099 ohne Authentifizierung bereitgestellt. Dieser Port darf nicht aus nicht vertrauenswürdigen Netzwerken erreichbar sein. Die Endpoints env, configprops und heapdump geben darüber hinaus Konfigurationswerte und Speicherinhalte inklusive Zugangsdaten preis. Freischaltungen sind daher nach Abschluss der Analyse wieder zu entfernen.

Aktivierung des DEBUG Logs im System-Portal

Voraussetzung sind ein aktiviertes System-Portal sowie ein freigeschalteter loggers-Endpoint, siehe die beiden vorangehenden Abschnitte.

  1. In Relution als System-Administrator anmelden. Der Standard-Benutzername ist admin.

  2. Im Support-Menü (Fragezeichen-Symbol) System Portal öffnen.

    System-Portal im Relution Support-Menü öffnen

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

    Relution Instanz im System-Portal aufrufen

  4. In den Bereich Logger wechseln.

    Logger-Bereich im Relution System-Portal öffnen

  5. Die Suche nutzen, um die entsprechenden Logger auf DEBUG zu stellen. ROOT aktiviert sämtliche Logger und ist daher nur in Ausnahmefällen zu nutzen, da schnell viel Inhalt generiert wird. Im Beispiel ist die AppleMdmResource aktiviert worden.

    Logger auf DEBUG-Level im Relution System-Portal setzen

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

Bei einem Logging auf 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.

Neue Berechtigung für Logging-Konfiguration in Relution System-Organisation erstellen

Logging-Benutzer mit Berechtigung in Relution System-Organisation anlegen

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.

Access Token für Logging-Benutzer in Relution Benutzerprofil erstellen

Generierten Access Token für Logging-Benutzer anzeigen und kopieren

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.

Logging-User in Relution Web API autorisieren und Loglevel steuern

Logging-Konfiguration per Web API mit Access Token ausführen

Paketnamen und Loglevel im Formular des Endpoints logging der Relution Web API

Curl-Befehl und Antwortcode 204 nach dem Ausführen in der Relution Web API

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.

Logging-Punkte in Relution Web API zurücksetzen oder wiederherstellen

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.

Loglevel per Curl-Befehl steuern und als Alias speichern

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 →.

Wie hilfreich war dieser Artikel?