SOP Observabilité et Audit

Cette page explique où les preuves d’exécution des SOP sont stockées et comment les inspecter.

1. Persistance de l’audit

Les entrées d’audit de SOP sont persistées via SopAuditLogger dans le backend Memory configuré, sous la catégorie sop.

Schémas de clés courants :

• sop_run_{run_id} : instantané d’exécution (mises à jour de début et de fin)
• sop_step_{run_id}_{step_number} : résultat par étape
• sop_approval_{run_id}_{step_number} : enregistrement d’approbation de l’opérateur
• sop_timeout_approve_{run_id}_{step_number} : enregistrement d’approbation automatique de délai d’expiration

2. Chemins d’inspection

2.1 Journaux d’exécution

Chaque appel au fournisseur, appel d’outil et événement de cycle de vie émis dans une étape de SOP hérite de l’attribution stable zeroclaw.sop_run_id. La page de détail d’exécution de la passerelle affiche ces événements sous forme de chronologie. La CLI et le volet Logs de ZeroCode interrogent la même trace d’exécution persistée et épurée, plutôt que de maintenir un stockage de journaux SOP distinct.

Chaque étape terminée, en échec ou ignorée émet également un événement de résultat structuré. Son message contient un bref résumé du résultat, et son attributes.output contient jusqu’à 4 096 caractères de sortie épurée des identifiants, ainsi que le numéro d’étape, le statut, l’agent effectif et le nombre d’appels d’outils capturés. Le résultat canonique et non tronqué de l’étape reste dans l’enregistrement d’audit SOP ; la projection bornée permet au journal d’exécution partagé d’être affiché et recherché en toute sécurité.

zeroclaw sop logs <run-id>
zeroclaw sop logs <run-id> --limit 500 --json

Dans ZeroCode, ouvrez Journaux et appuyez sur r pour saisir un identifiant d’exécution ; appuyez sur R pour effacer le filtre d’exécution. Les clients API peuvent utiliser GET /api/logs?sop_run_id=<run-id> et paginer avec next_cursor_line_offset, exactement comme pour toute autre requête de journaux.

Le lecteur inclut un pont de compatibilité restreint pour les événements écrits avant l’existence de zeroclaw.sop_run_id, lorsque ces lignes contenaient attributes.run_id ou un message de début ou de fin d’audit SOP hérité. Les événements de fournisseur et d’outil issus d’anciennes exécutions ne peuvent pas être reconstruits s’ils n’ont jamais contenu l’identifiant d’exécution.

Les journaux d’exécution suivent la politique de persistance et de rétention configurée pour la trace d’exécution. La passerelle ne lit que le fichier JSONL actif courant ; une exécution suffisamment ancienne peut donc ne plus avoir de lignes conservées après un nettoyage glissant ou une rotation. L’UI et la CLI signalent lorsque la persistance est désactivée ; les archives de rotation restent des artefacts de diagnostic hors ligne.

Un build observability-otel avec backend = "otel" exporte également ces mêmes événements canoniques sous forme de LogRecords OTLP/HTTP protobuf standard. Les lignes de fournisseur, d’outil et d’étape conservent zeroclaw.sop_run_id comme attribut OTel, afin qu’un collecteur ou un fournisseur puisse interroger la même exécution sans remplacer le chemin local tableau de bord/CLI/TUI. Voir Journaux et observabilité.

2.2 Interface en ligne de commande au niveau des définitions

zeroclaw sop list
zeroclaw sop validate [name]
zeroclaw sop show <name>

Outils d’état d’exécution du runtime

L’état d’exécution de la SOP est interrogé via les outils intégrés à l’agent :

• sop_status : exécutions actives/terminées et métriques optionnelles
• sop_status avec include_gate_status: true : phase de confiance et état de l’évaluateur de portes (le cas échéant)
• sop_approve : approuver l’étape d’exécution en attente
• sop_advance : soumettre le résultat de l’étape et faire avancer l’exécution

3. Métriques

• /metrics expose les métriques d’observateur lorsque [observability] backend = "prometheus".
• Les noms exportés actuels sont les familles zeroclaw_* (métriques générales du runtime).
• Les agrégats spécifiques à un SOP sont disponibles via sop_status avec include_metrics: true.