.. Zdroj: elza/docs/admin-guide/source/08-monitoring.rst, elza e87a93d6d1

.. _admin_monitoring:

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

Elza poskytuje kontroly stavu (health) a metriky ve formátu Prometheus
(`Spring Boot Actuator
<https://docs.spring.io/spring-boot/reference/actuator/index.html>`_).
Lze je napojit na běžné dohledové nástroje jako Prometheus, Grafana nebo
Zabbix.

.. _admin_monitoring_config:

Správcovský port
================

Endpointy monitorování jsou ve výchozím stavu zapnuté. Jsou publikovány
na samostatném správcovském portu ``8081`` navázaném na ``127.0.0.1``,
jsou tedy dostupné pouze ze samotného serveru. Aplikační port tím není
dotčen. Vestavěné výchozí hodnoty jsou:

.. 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``. Libovolnou
hodnotu lze přepsat v :file:`elza.yaml` nebo proměnnou prostředí
(například ``MANAGEMENT_SERVER_PORT``).

.. warning::

   Endpointy monitorování nevyžadují autentizaci; jsou chráněny tím, že
   jsou dostupné jen lokálně. Pokud má metriky sbírat vzdálený server
   Prometheus, změňte ``management.server.address`` a přístup k portu
   omezte jinak (firewall, reverzní proxy s autentizací). Port nikdy
   nepublikujte do veřejné sítě.

.. _admin_monitoring_access:

Endpointy
=========

``http://127.0.0.1:8081/actuator/health``
   Celkový stav (``UP`` / ``DOWN``) se stavem jednotlivých komponent
   (databáze, místo na disku, LDAP, je-li nastaven).
``http://127.0.0.1:8081/actuator/health/liveness`` a ``.../readiness``
   Sondy životnosti a připravenosti pro load balancery nebo orchestrátory
   kontejnerů.
``http://127.0.0.1:8081/actuator/prometheus``
   Metriky ve formátu Prometheus.

Příklad:

.. code-block:: console

   $ curl http://127.0.0.1:8081/actuator/health
   {"status":"UP","components":{"db":{"status":"UP"},"diskSpace":{"status":"UP"},
    "livenessState":{"status":"UP"},"ping":{"status":"UP"},"readinessState":{"status":"UP"}}}

Kontrola LDAP je součástí stavu jen při nastavené autentizaci přes LDAP
(``elza.security.ldap.ad-domain``); pak kontroluje nastavený server LDAP.
Vypnout ji lze volbou ``management.health.ldap.enabled: false``.

.. _admin_monitoring_metrics:

Metriky Elzy
============

Kromě standardních metrik JVM, HTTP serveru (``http_server_requests_*``),
poolu databázových spojení (HikariCP) a systému publikuje Elza metriky
své fronty synchronizace s externími systémy (typicky CAM) a svého
plánovače úloh. Metriky nemají štítky (labels); hodnoty fronty jsou
agregovány přes všechny nastavené externí systémy. Metriky stáří vracejí
``-1``, pokud není co měřit.

.. list-table::
   :header-rows: 1
   :widths: 34 46 20

   * - Metrika
     - Význam
     - Doporučené upozornění
   * - ``elza_cam_last_success_age_seconds``
     - Počet sekund od posledního úspěšného dotazu na externí systém CAM
       (nejstarší hodnota přes všechny systémy). I dotaz, který nenajde
       žádnou změnu, je úspěšný. Hlavní ukazatel dostupnosti CAM.
     - nad 7200
   * - ``elza_cam_error_count``
     - Počet položek synchronizace ve stavu chyba (například neúspěšné
       odeslání do CAM).
     - nad 0
   * - ``elza_cam_oldest_error_age_seconds``
     - Počet sekund od poslední změny stavu nejstarší chybové položky.
       Dává počtu chyb závažnost a zabraňuje upozorněním u přechodných
       chyb.
     - nad 3600
   * - ``elza_cam_deferred_oldest_age_seconds``
     - Počet sekund od poslední změny stavu nejstarší odložené položky
       (například nahrazení entitou, která ještě není k dispozici).
       Odložené položky se obvykle vyřeší samy.
     - nad 86400
   * - ``elza_cam_pending_oldest_age_seconds``
     - Počet sekund od chvíle, kdy nejstarší položka čekající na stažení
       nebo odeslání vstoupila do svého stavu. Roste, když se fronta
       nezpracovává, což metrika posledního úspěchu nezachytí.
     - nad 3600
   * - ``elza_scheduler_heartbeat_age_seconds``
     - Počet sekund od posledního tiku plánovače úloh. Roste bez omezení,
       pokud plánovač zamrzne; tím se zastaví synchronizace s CAM i
       všechny další plánované úlohy až do restartu.
     - nad 300
   * - ``elza_scheduler_longest_running_task_seconds``
     - Počet sekund, po které běží nejdéle běžící plánovaná úloha; ``-1``
       v nečinnosti. Pro diagnostiku; úloha běžící déle než
       ``elza.monitoring.scheduler.stuckThresholdSeconds`` se navíc zapíše
       do logu s výpisem zásobníku.
     - žádné
   * - ``elza_users_connected``
     - Počet připojených uživatelů (session WebSocket). Informativní.
     - žádné

Strojově čitelný seznam těchto metrik s doporučenými prahy je součástí
distribuce: :file:`server/config/csc-metrics.json`.

Plánovač lze ladit volbami ``elza.monitoring.scheduler.poolSize``
(výchozí 4 vlákna), ``elza.monitoring.scheduler.heartbeatMs`` (výchozí
30000) a ``elza.monitoring.scheduler.stuckThresholdSeconds`` (výchozí
1800).

.. _admin_deployment_scripts_reporting:

Hlášení stavu dohledovému systému
=================================

Příkaz ``elza-health`` instalačních skriptů umí hlásit stav instance
vzdálenému dohledovému systému. LightComp v.o.s. nabízí takovou službu
v rámci podpory (Customer Service Center, CSC); lze použít i jiný systém,
který implementuje stejné rozhraní.

- Hlášení je aktivní jen při nastavených přístupových údajích
  (``CUSTOMER_ID`` a ``CUSTOMER_SERVICE_SECRET`` v :file:`elza-env`). Bez
  nich skripty stav kontrolují jen lokálně a nic neodesílají.
- Komunikace probíhá pouze směrem od instance k dohledovému systému
  (push) protokolem HTTPS; každé hlášení je podepsáno klíčem zákazníka
  (HMAC). Dohledový systém se nikdy nepřipojuje do infrastruktury
  zákazníka.

Každé hlášení (ve výchozím nastavení každých 10 minut,
``HEARTBEAT_INTERVAL``) obsahuje:

- celkový stav instance (``up`` / ``degraded`` / ``down``),
- výsledky dílčích kontrol (stav služby systemd, HTTP kontrola),
- verzi aplikace a čas jejího spuštění,
- název počítače,
- hodnoty metrik uvedených v :file:`csc-metrics.json`.

Odesílají se jen číselné hodnoty uvedených metrik (allow-list); žádný
archivní obsah, osobní údaje ani úplný výpis metrik. Pro vypnutí
odesílání metrik při zachování hlášení stavu nastavte ``CSC_METRICS_URL``
na prázdnou hodnotu; pro úplné vypnutí hlášení odstraňte přístupové
údaje.

Další nastavení skriptů popisuje https://get.lightcomp.com/elza/.
