Logging

10. Logging#

Nubus components produce log messages that help operators monitor system behavior and troubleshoot issues. This section describes the logging capabilities of Nubus, including structured logging and how to configure logging levels.

10.1. Structured logging#

Structured logging outputs log messages in a standardized format with consistent fields. This format supports integration with log management systems, such as Elasticsearch or similar tools. Structured logging is available for the following deployments:

Nubus for UCS:: Since 5.2-4. Activated by default.
Nubus for Kubernetes:: Since 1.22.0. Activated by default.

10.1.1. Affected components#

The following components support structured logging:

Nubus for UCS

UMC Server
UDM HTTP REST API
UDM CLI
AD Connector
S4 Connector
Directory Notifier
Directory Listener

Nubus for Kubernetes

UDM HTTP REST API
UMC Server
Directory Notifier
Directory Listener
AD Connector

10.1.2. Log format#

Structured log lines use the format in Listing 10.1. You find an example in Listing 10.2.

Listing 10.1 Log format for a line in structured logging#

<timestamp> <severity:8> [<request ID>] <message>\t| <app data> <source code reference> [PID] [log facility] [traceback]

The fields have the following meaning:

timestamp: ISO 8601 formatted timestamp with sub-second precision and timezone, for example 2023-10-27T08:22:57.275138+00:00.
severity: Log level, padded to 8 characters. For the available levels, see Logging levels.
request ID: Correlation ID for tracking requests across services. A dash (-) indicates no request ID.
message: The log message text.
app data: Key-value pairs with application-specific data in logfmt format.
source code reference: Python module and line number that produced the log entry.
PID: Process ID, optional.
log facility: Log facility, optional.
traceback: Exception traceback, optional.

Listing 10.2 Example for structured 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. Parsing log lines#

To parse structured log lines, use the Python regular expression in Listing 10.3. Lines that don’t match this pattern are tracebacks or legacy univention.debug calls. You can ignore them when parsing structured logs.

Listing 10.3 Regular expression in Python for structured log lines#

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. Configure structured logging#

To change the structured logging setting, use the following configuration for your deployment.

Nubus for UCS

Nubus for UCS activates structured logging by default. To deactivate structured logging, use the following steps.

Set the respective UCR variables to false as shown in Listing 10.4. For a complete list of UCR variables, see UCR variable reference for structured logging.
Listing 10.4 Deactivate structured logging on Nubus for UCS#
```
$ ucr set \
   umc/server/debug/structured-logging=false \
   directory/manager/rest/debug/structured-logging=false
```
Restart the affected services to apply the changes as shown in Listing 10.5.
Listing 10.5 Restart services after changing structured logging#
```
$ systemctl restart univention-management-console-server
$ systemctl restart univention-directory-manager-rest
```

To re-enable structured logging, repeat the steps, set the same variables to true, and restart the services.

Nubus for Kubernetes

Nubus for Kubernetes activates structured logging by default. To deactivate structured logging, use the following steps.

Add the configuration in Listing 10.6 to your custom_values.yaml values file.

The configuration values correspond to the pattern of UCR variables. For a complete list of UCR variables, see UCR variable reference for structured logging.

Listing 10.6 Deactivate structured logging for affected components#

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"

After updating your configuration, apply the changes as described in Apply configuration in Univention Nubus for Kubernetes - Operation Manual [1].

To re-enable structured logging, remove the overrides from your custom_values.yaml values file and the default is restored.

10.2. Logging levels#

Structured logging in Nubus offers the logging levels as described in Table 10.1.

Table 10.1 Logging levels available in Nubus#
Level	Name	Description
0	ERROR	Only error messages.
1	WARNING	Warnings and errors.
2	PROCESS	Process lifecycle events, such as state transitions.
3	INFO	Informational messages about normal operations. This is the default setting.
4	DEBUG	Debug messages.
5	TRACE	Trace-level logging for detailed debugging.

10.2.1. Configure logging levels#

To change the logging level for specific components, use the following configuration for your deployment.

Nubus for UCS

To change the logging level, use the following steps:

Set the respective UCR variables as shown in Listing 10.7. For a complete list of UCR variables, see UCR variable reference for structured logging.
Listing 10.7 Configure logging levels on Nubus for UCS#
```
$ ucr set \
   umc/server/debug/level=3 \
   directory/manager/rest/debug_level=3
```
Restart the affected services to apply the changes, as shown in Listing 10.8.
Listing 10.8 Restart services after changing logging levels#
```
$ systemctl restart univention-management-console-server
$ systemctl restart univention-directory-manager-rest
```

Nubus for Kubernetes

To change the logging level for specific components, use the following steps:

Add the configuration in Listing 10.9 to your custom_values.yaml values file.

The configuration values correspond to the pattern of UCR variables. For a complete list of UCR variables, see UCR variable reference for structured logging.

Listing 10.9 Configure logging levels for components#

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

After updating your configuration, apply the changes as described in Apply configuration in Univention Nubus for Kubernetes - Operation Manual [1].

10.3. UCR variable reference for structured logging#

Table 10.2 lists all UCR variables for structured logging on Nubus for UCS. The default value is true, meaning enabled.

Table 10.2 UCR variables for structured logging#
Component	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`

Nubus Manual 1.x

Logging

Contents

10. Logging#

10.1. Structured logging#

10.1.1. Affected components#

10.1.2. Log format#

10.1.3. Parsing log lines#

10.1.4. Configure structured logging#

10.2. Logging levels#

10.2.1. Configure logging levels#

10.3. UCR variable reference for structured logging#