Logging

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

10.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.22.0. Standardmäßig aktiviert.

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

10.1.2. Protokollformat#

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

Quellcode 10.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 10.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

10.1.3. Logging-Zeilen analysieren#

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

Quellcode 10.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>.*?)$"
)

10.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 10.4 gezeigt. Eine vollständige Liste der UCR-Variablen finden Sie unter UCR-Variablen für strukturiertes Logging.

    Quellcode 10.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 10.5 gezeigt.

    Quellcode 10.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 aktiviert strukturiertes Logging standardmäßig. Zum Deaktivieren des strukturierten Loggings führen Sie die folgenden Schritte aus.

  1. Fügen Sie die Konfiguration in Quellcode 10.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 10.6 Strukturiertes Logging für betroffene Komponenten deaktivieren#
    global:
  configUcr:
    umc:
      server:
        debug:
          structured-logging: "false"
      module:
        debug:
          structured-logging: "false"
    directory:
      manager:
        rest:
          debug:
            structured-logging: "false"
    listener:
      debug:
        structured-logging: "false"
    notifier:
      debug:
        structured-logging: "false"
    connector:
      ad:
        debug:
          structured-logging: "false"

  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.

Um strukturiertes Logging erneut zu aktivieren, entfernen Sie die Anpassungen aus Ihrer custom_values.yaml Datei, und der Standardwert wird wiederhergestellt.

10.2. Logging-Level#

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

Tab. 10.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.

10.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 10.7 gezeigt. Eine vollständige Liste der UCR-Variablen finden Sie unter UCR-Variablen für strukturiertes Logging.

    Quellcode 10.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 10.8 gezeigt.

    Quellcode 10.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 10.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 10.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.

10.3. UCR-Variablen für strukturiertes Logging#

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

Tab. 10.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