Logging

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

9.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.17.0. Deactivated by default.

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

9.1.2. Log format#

Structured log lines use the format in Listing 9.1. You find an example in Listing 9.2.

Listing 9.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 9.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

9.1.3. Parsing log lines#

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

Listing 9.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>.*?)$"
)

9.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 9.4. For a complete list of UCR variables, see UCR variable reference for structured logging.
Listing 9.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 9.5.
Listing 9.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 deactivates structured logging by default. To activate structured logging, use the following steps.

Add the configuration in Listing 9.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 9.6 Activate structured logging for affected components#

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"

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

To deactivate structured logging, repeat the steps, set the values to "false", and apply the changes.

9.2. Logging levels#

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

Table 9.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.

9.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 9.7. For a complete list of UCR variables, see UCR variable reference for structured logging.
Listing 9.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 9.8.
Listing 9.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 9.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 9.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].

9.3. UCR variable reference for structured logging#

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

Table 9.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

9. Logging#

9.1. Structured logging#

9.1.1. Affected components#

9.1.2. Log format#

9.1.3. Parsing log lines#

9.1.4. Configure structured logging#

9.2. Logging levels#

9.2.1. Configure logging levels#

9.3. UCR variable reference for structured logging#