Contrat 1.3.3 : routes /v1, champs JSON, erreurs et métriques Prometheus. La version du schéma du journal reste indépendante.
La liste courante containers reste vide et /readyz renvoie 503. Le champ facultatif last_complete_snapshot contient les données historiques. Le champ failed_action identifie l’action et le conteneur quand ils sont connus.
Agent privé et interface publique
L’agent écoute par défaut sur 127.0.0.1:9808. Les routes ci-dessous concernent directement cet agent. Le mandataire Nginx de l’interface expose moins de routes et ajoute son authentification. La démonstration publique ne transmet pas /metrics, /healthz, /readyz ni la réception des notifications.
Les lectures utilisent les données en mémoire et ne déclenchent ni cycle de collecte ni action Docker. Les réponses JSON utilisent application/json; charset=utf-8, avec interdiction de mise en cache. HEAD conserve le statut et les en-têtes de représentation, sans corps. Aucun point d’entrée ne modifie la configuration.
Routes et accès
| Route | Méthodes et réponse | Accès |
|---|---|---|
/healthz | GET, HEAD · 200 si le serveur répond. | Sans identifiant au niveau de l’agent. |
/readyz | GET, HEAD · 200 prêt, sinon 503. | Sans identifiant au niveau de l’agent. |
/v1/status | GET, HEAD · 200, même en état dégradé. | Jeton Bearer dédié si --status-token-file est activé. |
/metrics | GET, HEAD · 200, texte Prometheus. | Par défaut, /metrics reste ouvert. Pour exiger une authentification, ajoutez serve --metrics-token-file FICHIER et configurez Prometheus avec le jeton Bearer correspondant. Utilisez --status-token-file pour la lecture du statut. |
/v1/actions | POST · 202 avec la demande enregistrée. | Actions activées, jeton dédié et origine exacte. |
/v1/audit | GET, HEAD · 200 avec une page d’événements. | Lecture activée et jeton du journal. |
/v1/audit/export | GET, HEAD · 200, pièce jointe CSV ou JSONL. | Mêmes droits que la lecture du journal. |
/v1/notifications | POST · 202 avec le nombre de réceptions enregistrées. | Récepteur activé et jeton Bearer distinct. |
Les méthodes prises en charge mais incorrectes sur une route active renvoient 405 avec Allow. Les chemins inconnus, non canoniques et les fonctions protégées désactivées renvoient 404. Pas de CORS ni d’alias implicite avec barre oblique finale.
État, fraîcheur et champs absents
api_version vaut 1. Les clients doivent ignorer les champs supplémentaires. ready exige un dernier cycle réussi et une ancienneté monotone inférieure ou égale au seuil configuré. running signale un cycle en cours ; un précédent résultat encore frais peut rester prêt pendant cette collecte.
Avant la première réussite, après une erreur ou lorsque les données sont périmées, containers vaut []. Le statut reste HTTP 200 ; /readyz renvoie 503. Les dates de réussite et les compteurs restent consultables. Une simple péremption n’ajoute pas d’erreur. L’exécution d’une action manuelle invalide la fraîcheur avant la mutation.
Les mesures inconnues ou non demandées sont null dans les objets JSON ; elles sont absentes des échantillons Prometheus. Un zéro connu reste un zéro. Les tailles sont en octets, les dates en secondes Unix et les pourcentages en unités 0–100 ; le processeur peut dépasser 100 sur plusieurs cœurs.
manual_actions est toujours présent : {"enabled":false} si désactivé, sinon les états autorisés et au plus 32 demandes récentes. audit_enabled indique la disponibilité du lecteur du journal. Les compteurs actions concernent uniquement les décisions automatiques, dont maintenance.
Demandes manuelles et erreurs
Le corps JSON contient exactement request_id, container_id et action. Les identifiants sont respectivement 32 et 64 caractères hexadécimaux minuscules. Découvrez les commandes disponibles dans manual_actions.allowed_states, y compris les commandes de maintenance lorsqu’elles sont activées.
Une réponse 202 confirme la prise en compte, pas la réussite de l’action. Les états sont queued, running, succeeded et failed. Consultez manual_actions.recent pour l’issue. Un identifiant encore conservé, avec le même contenu et le même acteur, retourne la demande existante sans réexécution. Un autre contenu ou acteur renvoie 409. Cette protection disparaît après éviction ou redémarrage du processus.
La file autorise une demande en attente ou en cours pour l’agent. La protection du conteneur, sa sélection, son état et le délai entre actions sont revérifiés avant exécution. Une demande acceptée peut donc échouer ensuite. Le délai maximal d’attente est vérifié au retrait de la file, après plus de 60 secondes.
Les erreurs sont des objets {"error":"reason"} : 400 pour une demande invalide, 403 pour les droits ou un conteneur protégé, 409 pour une condition non satisfaite, 413 pour la taille, 415 pour le type de contenu et 503 pour un journal indisponible. Les motifs restent en anglais. La référence complète précise chaque valeur et distingue refus initial et échec ultérieur.
Journal, curseurs et exports
Une page contient records, next_cursor, page_cursor, scanned_bytes et limit. Elle est bornée à 100 événements, 1 Mio de lecture et 512 Kio de données d’événements encodées, auxquels s’ajoute l’enveloppe de réponse. Une page vide peut encore proposer un curseur vers des événements plus anciens.
Les filtres se combinent avec ET : since, until, container, source, category, result et correlation_id. Le conteneur est recherché par sous-chaîne sans distinction de casse ; la corrélation exige l’identifiant exact. Les dates doivent préciser le fuseau. Les paramètres inconnus ou répétés sont refusés.
Les curseurs sont liés aux filtres et à l’acteur, excluent les ajouts ultérieurs et expirent après 15 minutes ou perte des données nécessaires. Après redémarrage, leur signature n’est plus valide : 400 invalid_cursor. Une expiration reconnue renvoie 410 cursor_expired. Un échec de lecture renvoie 503, jamais une page vide présentée comme complète.
L’export utilise le page_cursor affiché et les mêmes filtres pour télécharger cette page seulement. La commande administrative audit-export reste destinée à l’ensemble des événements conservés. Consultez le guide du journal pour la rétention et l’échappement.
Métriques et notifications
Le catalogue des métriques précise noms, types, unités et étiquettes. Les tests couvrent chaque famille documentée. Les étiquettes de conteneur sont id et name, complétées selon la mesure par status, health, group, path ou window_seconds. L’ordre d’exposition et les textes d’aide ne sont pas figés.
Quand l’agent n’est pas prêt, les mesures de conteneurs sont omises ; les déclarations HELP/TYPE peuvent rester présentes. Les compteurs de l’agent repartent à zéro au redémarrage. Les nombres d’événements dans une fenêtre sont des jauges, pas des compteurs cumulés.
Le récepteur de notifications accepte le format Alertmanager version 4 et répond {"recorded":N,"delivery_status":"not_reported"}. Cela confirme l’enregistrement de la réception, pas la livraison d’un courriel ou message Slack. Les reprises peuvent produire plusieurs réceptions corrélées. Une erreur de stockage au milieu d’un lot peut laisser les premières réceptions enregistrées.
Exemples de lecture
Ces commandes visent l’adresse privée de l’agent :
AGENT_URL='http://127.0.0.1:9808'
curl --fail-with-body --silent --show-error "$AGENT_URL/healthz"
curl --fail-with-body --silent --show-error "$AGENT_URL/readyz"
curl --fail-with-body --silent --show-error "$AGENT_URL/v1/status"
curl --fail-with-body --silent --show-error "$AGENT_URL/metrics"La référence complète fournit aussi les commandes curl pour soumettre une action autorisée, consulter sa corrélation et exporter exactement la page affichée. Ces exemples nécessitent vos jetons privés et une origine configurée ; ils ne visent pas la démonstration publique.
Évolution du contrat
/v1 est conservé. Actions et notifications acceptent un unique en-tête application/json avec paramètres facultatifs, dont charset=utf-8. Le corps reste UTF-8 ; les en-têtes de type de contenu dupliqués sont refusés avec 415. Les futures ruptures suivent la politique de dépréciation.