Journalisation

Niveaux

L'option log_level contrôle la verbosité, du plus bavard au plus silencieux :

Niveau	Ce que vous obtenez
trace	métadonnées des trames WebSocket, arguments des outils
debug	commandes WebSocket, appels HTTP vers HA, requêtes MCP, invocations d'outils
info	résumé de démarrage, cycle de vie de la connexion (défaut)
notice	événements notables : tentatives non autorisées, jeton reporté dans les options
warning	problèmes récupérables : reconnexions, échecs d'outils
error	refus de connexion HA, erreurs de lecture de configuration
fatal	échec de démarrage

La même valeur est appliquée à bashio (le wrapper run.sh), les lignes côté Supervisor suivent donc le même seuil.

Format

Une ligne par événement sur stderr, visible dans l'onglet Journal de l'add-on :

[2026-08-20T15:30:12.345Z] INFO mcp-ha x.y.z listening on port 9583 (MCP endpoint /mcp, health /health)
[2026-08-20T15:30:12.401Z] DEBUG WS command get_states (id 12)

Journal d'audit

Les tentatives d'écriture via ha_call_service produisent chacune une ligne JSON, quel que soit le niveau de log. C'est un enregistrement de sécurité, pas du debug : baisser la verbosité ne le fait jamais taire.

{"ts":"2026-08-20T15:31:02.000Z","audit":true,"tool":"ha_call_service","domain":"light","service":"turn_on","target":{"entity_id":["light.kitchen"]},"allowed":true,"result":"ok"}

Les tentatives refusées portent "allowed": false et une reason, et chaque ligne nomme le jeton à l'origine de l'appel (client). Aucun secret n'apparaît dans les lignes d'audit.

Depuis la 0.7.0, les lignes d'audit sont aussi persistées dans /data/audit.log (JSON lines). Le fichier tourne par taille : au-delà d'environ 1 Mo il devient audit.log.1 et un fichier neuf démarre, l'usage disque est donc borné à environ 2 Mo. Les écritures sont asynchrones et ne bloquent ni ne cassent jamais une requête ; si /data n'est pas accessible en écriture, un unique avertissement est journalisé et stdout reste la source de vérité.

Volontairement, aucun outil MCP ne lit ni ne vide ce fichier : un attaquant muni d'un jeton pourrait sinon effacer ses traces. Lisez-le en SSH ou avec un add-on éditeur de fichiers :

tail -f /data/audit.log   # depuis le conteneur de l'add-on

Secrets

Aucun secret n'est jamais journalisé en entier, à aucun niveau. Le jeton API n'apparaît que sous forme de préfixe masqué à remplissage fixe (d370f4f8**********) ; la valeur complète vit dans l'onglet Configuration de l'add-on. Un test unitaire garde cet invariant.

Diagnostiquer

• Problèmes de connexion : debug montre chaque commande WS et chaque reconnexion avec son délai de backoff.
• Comportement des outils : debug journalise chaque invocation, trace ajoute les arguments (tronqués).
• Authentification des clients : les requêtes non autorisées sont journalisées en notice avec l'adresse source.

En mode dev (hors add-on), le niveau se règle avec la variable d'environnement LOG_LEVEL.