.. _admin_monitoring:

=====================
Monitorování aplikace
=====================

Od verze 3.4.0 poskytuje Elza rozhraní pro sledování stavu aplikace (health)
a metriky ve formátu Prometheus. Rozhraní je založeno na technologii
`Spring Boot Actuator <https://docs.spring.io/spring-boot/reference/actuator/index.html>`_
a lze jej napojit na běžné dohledové nástroje (Prometheus, Grafana,
Zabbix a další).

Rozhraní zpřístupňuje:

 * celkový stav aplikace včetně stavu jednotlivých komponent
   (databáze, volné místo na disku),
 * sondy pro kontrolu životnosti a připravenosti (liveness/readiness),
 * metriky aplikace ve formátu Prometheus, zejména metriky fronty
   zpracování požadavků na synchronizaci s externími systémy.


.. _admin_monitoring_config:

------------------
Potřebná nastavení
------------------

Rozhraní pro monitorování je ve výchozím stavu zapnuté a není nutné je
aktivovat. Endpointy jsou publikovány na samostatném správcovském portu
``8081``, který je dostupný pouze z lokálního počítače (``127.0.0.1``).
Hlavní aplikační port není monitorováním nijak dotčen.

Výchozí hodnoty nastavení:

.. code-block:: yaml

  management:
    server:
      port: 8081
      address: 127.0.0.1
    endpoints:
      web:
        exposure:
          include: health,prometheus
    endpoint:
      health:
        probes:
          enabled: true
        show-details: always

Publikovány jsou pouze endpointy ``health`` a ``prometheus``, ostatní
endpointy technologie Actuator jsou vypnuty.

Uvedené hodnoty lze změnit v konfiguračním souboru :file:`elza.yaml`
(viz :ref:`Admin_config`), případně pomocí proměnných prostředí
(např. :token:`MANAGEMENT_SERVER_PORT`).

.. warning::

   Endpointy monitorování nejsou chráněny autentizací. Zabezpečení je
   založeno na tom, že správcovský port je dostupný pouze z lokálního
   počítače. Pokud je nutné zpřístupnit metriky vzdálenému dohledovému
   systému (např. serveru Prometheus), je třeba změnit
   :token:`management.server.address` a přístup k portu omezit jiným
   způsobem (firewall, reverzní proxy s autentizací). Rozhraní není
   určeno pro publikaci do veřejné sítě.


.. _admin_monitoring_access:

------------------
Přístup k rozhraní
------------------

Ve výchozím nastavení jsou endpointy dostupné z lokálního počítače na
těchto adresách:

 * ``http://127.0.0.1:8081/actuator/health`` - celkový stav aplikace
 * ``http://127.0.0.1:8081/actuator/health/liveness`` - sonda životnosti
 * ``http://127.0.0.1:8081/actuator/health/readiness`` - sonda připravenosti
 * ``http://127.0.0.1:8081/actuator/prometheus`` - metriky ve formátu Prometheus

Příklad ověření stavu aplikace:

.. code-block:: bash

   curl http://127.0.0.1:8081/actuator/health

Odpověď obsahuje celkový stav (``UP`` / ``DOWN``) a detail jednotlivých
komponent:

.. code-block:: json

   {
     "status": "UP",
     "components": {
       "db": { "status": "UP" },
       "diskSpace": { "status": "UP" },
       "livenessState": { "status": "UP" },
       "ping": { "status": "UP" },
       "readinessState": { "status": "UP" }
     }
   }

Sondy životnosti a připravenosti vrací pouze dílčí stav a jsou určeny
například pro kontroly orchestrátoru kontejnerů nebo load balanceru.

Metriky ve formátu Prometheus lze získat příkazem:

.. code-block:: bash

   curl http://127.0.0.1:8081/actuator/prometheus


.. _admin_monitoring_metrics:

-------------------
Publikované metriky
-------------------

Metriky fronty zpracování
-------------------------

Elza udržuje frontu zpracování požadavků na synchronizaci archivních
entit s externími systémy (typicky CAM). Položky fronty mohou čekat na
zpracování, být odloženy (např. při nahrazení entity, jejíž nahrazující
entita ještě není dostupná) nebo skončit chybou. Následující metriky
umožňují dohledovému systému rozpoznat zaseknutou nebo chybující frontu:

.. list-table::
   :header-rows: 1
   :widths: 40 12 12 36

   * - Metrika (Prometheus)
     - Typ
     - Jednotka
     - Význam
   * - ``elza_cam_last_success_age_seconds``
     - gauge
     - sekundy
     - Stáří posledního úspěšného dotazu na externí systém (bere se
       nejstarší hodnota přes všechny nakonfigurované systémy). Úspěchem
       je i dotaz bez nových změn. Hlavní ukazatel dostupnosti externího
       systému.
   * - ``elza_cam_error_count``
     - gauge
     - počet
     - Počet položek fronty ve stavu chyba (např. neúspěšné odeslání),
       součet přes všechny externí systémy.
   * - ``elza_cam_oldest_error_age_seconds``
     - gauge
     - sekundy
     - Stáří nejstarší položky ve stavu chyba.
   * - ``elza_cam_deferred_oldest_age_seconds``
     - gauge
     - sekundy
     - Stáří nejstarší odložené položky.
   * - ``elza_users_connected``
     - gauge
     - počet
     - Počet aktuálně připojených uživatelů. Informativní metrika.

Poznámky:

 * Metriky nemají žádné štítky (labels). Hodnoty jsou agregovány přes
   všechny nakonfigurované externí systémy, aby bylo možné použít
   jednotné prahové hodnoty.
 * Metriky typu stáří vrací hodnotu ``-1``, pokud není co měřit
   (např. žádný externí systém není nakonfigurován nebo fronta
   neobsahuje žádnou chybnou položku).

Standardní metriky
------------------

Kromě výše uvedených metrik jsou na endpointu ``prometheus`` dostupné
standardní metriky technologií Spring Boot a Micrometer, zejména:

 * metriky JVM (paměť, garbage collection, vlákna),
 * metriky HTTP serveru (``http_server_requests_*``),
 * metriky databázového poolu (HikariCP),
 * systémové metriky (CPU, uptime).

Strojově čitelný přehled metrik fronty zpracování, včetně výchozích
prahových hodnot pro upozornění, je součástí distribuce v souboru
:file:`config/csc-metrics.json`. Přehled metrik předávaných případnému
externímu dohledovému systému je uveden v kapitole
:ref:`admin_deployment_scripts_reporting`.