docs: premiere creation de documentation

Signed-off-by: GnomeZworc <nicolas.boufidjeline@g3e.fr>

docs/exploitation/observabilite.rst

@@ -0,0 +1,83 @@
+Observabilité
+=============
+
+Métriques Prometheus
+--------------------
+
+Exposées sur le port ``prometheus.port`` (9090 par défaut), alimentées par l'état lu en base :
+
+.. list-table::
+   :header-rows: 1
+   :widths: 40 60
+
+   * - Métrique
+     - Description
+   * - ``syonad_vpcs_total``
+     - nombre de VPC, par état
+   * - ``syonad_subnets_total``
+     - nombre de subnets, par état
+   * - ``syonad_vms_total``
+     - nombre de VM, par état
+
+Les états sont ceux du :doc:`cycle de vie </concepts/cycle-de-vie>`. Une valeur non nulle et
+durable sur ``error`` est l'alerte la plus utile à poser ; une valeur durable sur ``creating``
+ou ``deleting`` signale une opération qui n'aboutit pas.
+
+Watchdog
+--------
+
+Une goroutine périodique vérifie que les ressources marquées ``running`` en base existent
+toujours sur le système, et **notifie les écarts sans jamais réparer**.
+
+.. code-block:: yaml
+
+   watchdog:
+     enabled: true
+     interval_seconds: 60
+
+Il contrôle notamment l'existence des network namespaces, des liens réseau des subnets, des taps
+de VM et la réponse des units systemd associées.
+
+.. note::
+
+   Un écart persistant est signalé **à chaque tick**, sans déduplication. Le volume de
+   notifications est donc proportionnel à la durée de l'anomalie : c'est voulu, mais cela veut
+   dire qu'une alerte doit agréger, pas compter.
+
+Le watchdog étant strictement en lecture seule, une divergence entre la base et le système
+subsiste jusqu'à une action explicite (``DELETE`` puis recréation).
+
+Journaux
+--------
+
+``slog`` structuré, niveau réglé par ``logger.level`` (``debug``, ``info``, ``warn``, ``error``),
+``logger.debug: true`` forçant ``debug``.
+
+.. code-block:: bash
+
+   journalctl -u agent -f
+   journalctl -u 'metadata@i-web' -n 50
+   tail -f /var/log/dnsmasq-vp-admin_br-sn000001.log
+
+Inspection de la base
+---------------------
+
+En ligne de commande, sur l'host :
+
+.. code-block:: bash
+
+   /opt/two/bin/db -conf /etc/two/agent.yml
+
+.. warning::
+
+   ``db`` ouvre directement la base Badger. **Ne pas l'utiliser pendant que l'agent tourne** :
+   deux processus ne doivent pas ouvrir la même instance.
+
+L'API d'administration donne la même lecture sans ce risque, quand elle est activée :
+
+.. code-block:: bash
+
+   curl -s 'http://127.0.0.1:9091/db?prefix=vm/'
+
+Elle expose l'intégralité des valeurs, **y compris les hashs de mot de passe** — cf.
+:doc:`/exploitation/configuration`.