Logging

9. Logging#

Nubus-Komponenten erstellen Logging-Meldungen, die Betreibern helfen, das Systemverhalten zu überwachen und Probleme zu beheben. Dieser Abschnitt beschreibt die Logging-Funktionen von Nubus, einschließlich strukturiertem Logging und der Konfiguration von Logging-Level.

9.1. Strukturiertes Logging#

Strukturiertes Logging gibt Logging-Meldungen in einem standardisierten Format mit konsistenten Feldern aus. Dieses Format unterstützt die Integration mit Logging-Verwaltungssystemen wie Elasticsearch oder ähnlichen Tools. Strukturiertes Logging ist für die folgenden Bereitstellungen verfügbar:

Nubus für UCS:

Seit 5.2-4. Standardmäßig aktiviert.

Nubus für Kubernetes:

Seit 1.17.0. Standardmäßig deaktiviert.

9.1.1. Betroffene Komponenten#

Die folgenden Komponenten unterstützen strukturiertes Logging:

  • UMC Server

  • UDM HTTP REST API

  • UDM CLI

  • AD Connector

  • S4 Connector

  • Directory Notifier

  • Directory Listener

  • UDM HTTP REST API

  • UMC Server

  • Directory Notifier

  • Directory Listener

  • AD Connector

9.1.2. Protokollformat#

Strukturiertes Logging verwendet für eine Zeile das Format in Quellcode 9.1. Ein Beispiel finden Sie in Quellcode 9.2.

Quellcode 9.1 Format einer Zeile für strukturiertes Logging#
<timestamp> <severity:8> [<request ID>] <message>\t| <app data> <source code reference> [PID] [log facility] [traceback]

Die Felder haben folgende Bedeutung:

timestamp

ISO 8601 formatierter Zeitstempel mit Sekundenbruchteilen und Zeitzone, beispielsweise 2023-10-27T08:22:57.275138+00:00.

severity

Logging-Level immer auf 8 Zeichen aufgefüllt. Für die verfügbaren Level siehe Logging-Level.

request ID

ID zum Verfolgen von Anfragen über Services hinweg. Ein Bindestrich (-) zeigt an, dass keine Request-ID vorhanden ist.

message

Die Nachricht aus der Logging-Meldung.

app data

Schlüssel-Wert-Paare mit anwendungsspezifischen Daten im Format logfmt.

source code reference

Python-Modul und Zeilennummer, die den Logging-Eintrag erzeugt haben.

PID

Prozess-ID, optional.

log facility

Log-Facility, optional.

traceback

Exception Traceback, optional.

Quellcode 9.2 Beispiel für strukturiertes Logging#
2023-10-27T08:22:57.275138+00:00 INFO     [31f863092a] modified group        | dn="..." module=app.main pid=13825
2023-10-27T08:22:58.123454+00:00 DEBUG    [         -] received request      | method="POST" module=app.net pid=13825

9.1.3. Logging-Zeilen analysieren#

Zum Analysieren strukturierter Logging-Zeilen verwenden Sie in Python den regulären Ausdruck in Quellcode 9.3. Zeilen, die diesem Muster nicht entsprechen, sind Tracebacks oder ältere univention.debug Aufrufe. Sie können diese bei der Analyse ignorieren.

Quellcode 9.3 Regulärer Ausdruck in Python für strukturierte Logging-Zeilen#
REGEX = (
    r"^(?P<date>\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}\.\d{3,6}\+\d{2}:?\d{2}) +"
    r"(?P<level>\w+?) +\[(?P<request_id>.*?)\] (?P<message>.+?)\t\| (?P<data>.*?)$"
)

9.1.4. Strukturiertes Logging konfigurieren#

Zum Ändern der Einstellung für strukturiertes Logging verwenden Sie die folgende Konfiguration für Ihre Bereitstellung.

Nubus für UCS aktiviert strukturiertes Logging standardmäßig. Zum Deaktivieren des strukturierten Loggings führen Sie die folgenden Schritte aus.

  1. Setzen Sie die entsprechenden UCR-Variablen auf false, wie in Quellcode 9.4 gezeigt. Eine vollständige Liste der UCR-Variablen finden Sie unter UCR-Variablen für strukturiertes Logging.

    Quellcode 9.4 Strukturiertes Logging auf Nubus für UCS deaktivieren#
    $ ucr set \
   umc/server/debug/structured-logging=false \
   directory/manager/rest/debug/structured-logging=false

  2. Starten Sie die betroffenen Services neu, um die Änderungen anzuwenden, wie in Quellcode 9.5 gezeigt.

    Quellcode 9.5 Services nach dem Ändern der strukturierten Loggings neu starten#
    $ systemctl restart univention-management-console-server
$ systemctl restart univention-directory-manager-rest

Zum erneuten Aktivieren des strukturierten Loggings wiederholen Sie die Schritte, setzen Sie die gleichen Variablen auf true und starten Sie die Services neu.

Nubus für Kubernetes deaktiviert strukturiertes Logging standardmäßig. Zum Aktivieren des strukturierten Loggings führen Sie die folgenden Schritte aus.

  1. Fügen Sie die Konfiguration in Quellcode 9.6 zu Ihrer custom_values.yaml Datei hinzu.

    Die Konfigurationswerte entsprechen dem Muster der UCR-Variablen. Eine vollständige Liste der UCR-Variablen finden Sie unter UCR-Variablen für strukturiertes Logging.

    Quellcode 9.6 Strukturiertes Logging für betroffene Komponenten aktivieren#
    global:
  configUcr:
    umc:
      server:
        debug:
          structured-logging: "true"
      module:
        debug:
          structured-logging: "true"
    directory:
      manager:
        rest:
          debug:
            structured-logging: "true"
    listener:
      debug:
        structured-logging: "true"
    notifier:
      debug:
        structured-logging: "true"
    connector:
      ad:
        debug:
          structured-logging: "true"

  2. Nachdem Sie Ihre Konfiguration aktualisiert haben, wenden Sie die Änderungen wie in Apply configuration in Univention Nubus for Kubernetes - Operation Manual [1] beschrieben an.

Zum Deaktivieren des strukturierten Loggings wiederholen Sie die Schritte, setzen Sie die Werte auf "false" und wenden Sie die Änderungen an.

9.2. Logging-Level#

Strukturiertes Logging in Nubus bietet die Logging-Level, wie in Tab. 9.1 beschrieben.

Tab. 9.1 In Nubus verfügbare Logging-Level#

Stufe

Name

Beschreibung

0

ERROR

Nur Fehlermeldungen.

1

WARNING

Warnungen und Fehler.

2

PROCESS

Ereignisse aus dem Prozesslebenszyklus, wie Zustandsübergänge.

3

INFO

Informationsmeldungen über normale Vorgänge. Dies ist die Standardeinstellung.

4

DEBUG

Debug Meldungen.

5

TRACE

Logging auf Trace-Ebene für detailliertes Debugging.

9.2.1. Logging-Level konfigurieren#

Zum Ändern der Logging-Level für bestimmte Komponenten verwenden Sie die folgende Konfiguration für Ihre Installation.

Zum Ändern der Logging-Level führen Sie die folgenden Schritte aus:

  1. Setzen Sie die entsprechenden UCR-Variablen, wie in Quellcode 9.7 gezeigt. Eine vollständige Liste der UCR-Variablen finden Sie unter UCR-Variablen für strukturiertes Logging.

    Quellcode 9.7 Logging-Level auf Nubus für UCS konfigurieren#
    $ ucr set \
   umc/server/debug/level=3 \
   directory/manager/rest/debug_level=3

  2. Starten Sie die betroffenen Services neu, um die Änderungen anzuwenden, wie in Quellcode 9.8 gezeigt.

    Quellcode 9.8 Services nach dem Ändern der Logging-Level neu starten#
    $ systemctl restart univention-management-console-server
$ systemctl restart univention-directory-manager-rest

Zum Ändern der Logging-Level für bestimmte Komponenten führen Sie die folgenden Schritte aus:

  1. Fügen Sie die Konfiguration in Quellcode 9.9 zu Ihrer custom_values.yaml Datei hinzu.

    Die Konfigurationswerte entsprechen dem Muster der UCR-Variablen. Eine vollständige Liste der UCR-Variablen finden Sie unter UCR-Variablen für strukturiertes Logging.

    Quellcode 9.9 Logging-Level für Komponenten konfigurieren#
    global:
  configUcr:
    umc:
      server:
        debug:
          level: 3
      module:
        debug:
          level: 3
    directory:
      manager:
        rest:
          debug_level: 3
    listener:
      debug:
        level: 3
    notifier:
      debug:
        level: 3
    connector:
      ad:
        debug:
          level: 3

  2. Nachdem Sie Ihre Konfiguration aktualisiert haben, wenden Sie die Änderungen wie in Apply configuration in Univention Nubus for Kubernetes - Operation Manual [1] beschrieben an.

9.3. UCR-Variablen für strukturiertes Logging#

Tab. 9.2 listet alle UCR-Variablen für strukturiertes Logging auf Nubus für UCS auf. Der Standardwert ist true, was aktiviert bedeutet.

Tab. 9.2 UCR-Variablen für strukturiertes Logging#

Komponente

UCR-Variable

UMC Server

umc/server/debug/structured-logging

UMC Module

umc/module/debug/structured-logging

UDM HTTP REST API

directory/manager/rest/debug/structured-logging

UDM CLI

directory/manager/cmd/debug/structured-logging

AD Connector

connector/ad/debug/structured-logging

S4 Connector

connector/s4/debug/structured-logging

Directory Notifier

notifier/debug/structured-logging

Directory Listener

listener/debug/structured-logging
Auf dieser Seite