.. SPDX-FileCopyrightText: 2026 Univention GmbH
..
.. SPDX-License-Identifier: AGPL-3.0-only

.. _nubus-logging:

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

.. _nubus-logging-structured:

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.

.. _nubus-logging-structured-components:

Affected components
-------------------

The following components support structured logging:

.. tab-set::

   .. tab-item:: Nubus for UCS
      :sync: appliance

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

   .. tab-item:: Nubus for Kubernetes
      :sync: kubernetes

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

.. _nubus-logging-structured-format:

Log format
----------

Structured log lines use the format
in :numref:`nubus-logging-structured-format-listing`.
You find an example in :numref:`nubus-logging-structured-format-example-listing`.

.. code-block:: text
   :caption: Log format for a line in structured logging
   :name: nubus-logging-structured-format-listing

   <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 :ref:`nubus-logging-level`.

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

.. code-block:: text
   :caption: Example for structured logging
   :name: nubus-logging-structured-format-example-listing

   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

.. _nubus-logging-structured-parsing:

Parsing log lines
-----------------

To parse structured log lines,
use the Python regular expression
in :numref:`nubus-logging-structured-parsing-listing`.
Lines that don't match this pattern are tracebacks or legacy ``univention.debug`` calls.
You can ignore them when parsing structured logs.

.. code-block:: python
   :caption: Regular expression in Python for structured log lines
   :name: nubus-logging-structured-parsing-listing

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

.. _nubus-logging-structured-configure:

Configure structured logging
-----------------------------

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

.. tab-set::

   .. tab-item:: Nubus for UCS
      :sync: appliance

      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 :numref:`nubus-logging-structured-configure-appliance-listing`.
         For a complete list of UCR variables,
         see :ref:`nubus-logging-ucr-reference`.

         .. code-block:: console
            :caption: Deactivate structured logging on Nubus for UCS
            :name: nubus-logging-structured-configure-appliance-listing

            $ 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 :numref:`nubus-logging-structured-configure-appliance-restart-listing`.

         .. code-block:: console
            :caption: Restart services after changing structured logging
            :name: nubus-logging-structured-configure-appliance-restart-listing

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

   .. tab-item:: Nubus for Kubernetes
      :sync: kubernetes

      Nubus for Kubernetes deactivates structured logging by default.
      To activate structured logging,
      use the following steps.

      #. Add the configuration in :numref:`nubus-logging-structured-configure-k8s-listing`
         to your :file:`custom_values.yaml` values file.

         The configuration values correspond to the pattern of UCR variables.
         For a complete list of UCR variables,
         see :ref:`nubus-logging-ucr-reference`.

         .. code-block:: yaml
            :caption: Activate structured logging for affected components
            :name: nubus-logging-structured-configure-k8s-listing

            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 :external+uv-nubus-kubernetes-operation:ref:`nubus-configuration-apply`
         in :cite:t:`uv-nubus-kubernetes-operation`.

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

.. _nubus-logging-level:

Logging levels
==============

Structured logging in Nubus offers the logging levels
as described in :numref:`nubus-logging-level-table`.

.. _nubus-logging-level-table:

.. list-table:: Logging levels available in Nubus
   :header-rows: 1
   :widths: 1 2 9

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

.. _nubus-logging-level-configure:

Configure logging levels
------------------------

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

.. tab-set::

   .. tab-item:: Nubus for UCS
      :sync: appliance

      To change the logging level,
      use the following steps:

      #. Set the respective UCR variables
         as shown in :numref:`nubus-logging-level-configure-appliance-listing`.
         For a complete list of UCR variables,
         see :ref:`nubus-logging-ucr-reference`.

         .. code-block:: console
            :caption: Configure logging levels on Nubus for UCS
            :name: nubus-logging-level-configure-appliance-listing

            $ ucr set \
               umc/server/debug/level=3 \
               directory/manager/rest/debug_level=3

      #. Restart the affected services to apply the changes,
         as shown in :numref:`nubus-logging-level-configure-appliance-restart-listing`.

         .. code-block:: console
            :caption: Restart services after changing logging levels
            :name: nubus-logging-level-configure-appliance-restart-listing

            $ systemctl restart univention-management-console-server
            $ systemctl restart univention-directory-manager-rest

   .. tab-item:: Nubus for Kubernetes
      :sync: kubernetes

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

      #. Add the configuration in :numref:`nubus-logging-level-configure-k8s-listing`
         to your :file:`custom_values.yaml` values file.

         The configuration values correspond to the pattern of UCR variables.
         For a complete list of UCR variables,
         see :ref:`nubus-logging-ucr-reference`.

         .. code-block:: yaml
            :caption: Configure logging levels for components
            :name: nubus-logging-level-configure-k8s-listing

            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 :external+uv-nubus-kubernetes-operation:ref:`nubus-configuration-apply`
         in :cite:t:`uv-nubus-kubernetes-operation`.


.. _nubus-logging-ucr-reference:

UCR variable reference for structured logging
=============================================

:numref:`nubus-logging-ucr-reference-table` lists all UCR variables for structured logging on Nubus for UCS.
The default value is ``true``, meaning *enabled*.

.. _nubus-logging-ucr-reference-table:

.. list-table:: UCR variables for structured logging
   :header-rows: 1
   :widths: 4 6

   * - 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``