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

.. _nubus-metrics:

*******
Metrics
*******

Nubus components expose metrics,
so you can monitor your domain and diagnose problems.

.. warning::

   The metrics endpoint and its data model are **experimental**.

   Metric names, labels, and their meaning may change in future versions.
   Univention doesn't guarantee backward compatibility.

.. _nubus-metrics-endpoint:

Metrics endpoint
================

The *UDM HTTP REST API* provides a metrics endpoint at ``/univention/udm/-/metrics``.
This endpoint is compatible with Prometheus
and exposes metrics for monitoring and integrating with observability tools.

The endpoint requires authentication.
To access the endpoint,
you must be a member of the group ``udm-rest-metrics``
with the DN :samp:`cn=udm-rest-metrics,cn=groups,{ldap/base-dn}`,
or a member of any group with access to the *UDM HTTP REST API*.
For information about authorization groups in *UDM HTTP REST*,
see :external+uv-nubus-customization:ref:`customization-api-udm-rest-auth-group`
in :cite:t:`uv-nubus-customization`.

.. versionadded:: 5.2-5-errata-410

   Nubus creates the group ``udm-rest-metrics`` automatically during *UDM HTTP REST API* setup.
   See :uv:erratum:`5.2x410`.

.. _nubus-metrics-available-metrics:

Available metrics
=================

The endpoint returns data in the Prometheus exposition format.

.. _nubus-metrics-user-total:

Total number of managed, non-deactivated users
   This metric counts managed, non-deactivated user objects.

   .. code-block:: prometheus
      :caption: Total number of managed, non-deactivated users
      :name: nubus-metrics-user-total-number-listing

      # HELP nubus_users_user_total Total number of UDM objects of type users/user
      # TYPE nubus_users_user_total gauge
      nubus_users_user_total{license_uuid="<uuid>",domain="<domain>",platform="<platform>"} <count>

.. _nubus-metrics-user-limit:

License limit for active users
   If your Nubus domain doesn't have a license, this metric may return ``-1`` or ``+Inf``.

   .. code-block:: prometheus
      :caption: License limit for active users
      :name: nubus-metrics-user-limit-listing

      # HELP nubus_settings_license_users_limit_total Number of active users permitted by the installed license
      # TYPE nubus_settings_license_users_limit_total gauge
      nubus_settings_license_users_limit_total{license_uuid="<uuid>",domain="<domain>",platform="<platform>"} <limit>

.. _nubus-metrics-version:

Version
   Depending on your deployment type,
   you receive the following version information.

   .. tab-set::

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

         .. code-block:: prometheus
            :caption: UCS version information
            :name: nubus-metrics-platform-ucs-version-listing

            # HELP nubus_ucs_version_info UCS version information
            # TYPE nubus_ucs_version_info gauge
            nubus_ucs_version_info{
              license_uuid="<uuid>",
              domain="<domain>",
              ucs="<major>.<minor>",
              patch="<patch>",
              errata="<errata>",
              system_uuid="<uuid>"
            } 1

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

         .. code-block:: prometheus
            :caption: Nubus for Kubernetes version information
            :name: nubus-metrics-platform-n4k-version-listing

            # HELP nubus_n4k_version_info Nubus for Kubernetes version information
            # TYPE nubus_n4k_version_info gauge
            nubus_n4k_version_info{
              license_uuid="<uuid>",
              domain="<domain>",
              major="<major>",
              minor="<minor>",
              patch="<patch>"
            } 1

.. nubus-metrics-available-labels:

Available labels
================

.. _nubus-metrics-domain:

``domain``
   The domain name.
   All metrics include the ``domain`` label,
   which you can use to group and filter metrics.

``license_uuid``
   A stable identifier derived from the license ``keyId`` if available,
   otherwise from the license object's UUID.
   It provides a globally unique identifier for the deployment.

.. _nubus-metrics-platform-indicator:

``platform``
   Each metric, except the version metric,
   include a platform indicator
   that identifies the deployment type.
   The value is either ``ucs`` or ``k8s``.