Endpoints de santé

Sur cette page

Les endpoints
Réglages
Exemples
Dépannage

L'agent sert trois petits endpoints HTTP en lecture seule, pour que vous — ou Docker, Kubernetes, une plateforme de conteneurs, votre propre supervision — puissiez le vérifier depuis sa machine sans ouvrir Onagre.

Les endpoints#

Point de terminaison	Réponse	À utiliser comme
`GET /health`	`200` `{"status":"Healthy"}` tant que le processus tourne.	Sonde liveness.
`GET /ready`	`200` `{"status":"Ready"}` quand l'agent est connecté au Hub ; sinon `503` avec une `reason`.	Sonde readiness, vérification après installation.
`GET /status`	Version, durée de fonctionnement, connexion et activité.	Diagnostic.

Terminal

curl -s http://127.0.0.1:8080/ready

JSON

{ "status": "NotReady", "reason": "Hub stream not established: Another agent is already connected with this token" }

/status renvoie par exemple :

JSON

{
  "status": "Running",
  "version": "2.8.4.112",
  "startedAt": "2026-10-12T06:02:11Z",
  "uptimeSeconds": 13412,
  "ready": true,
  "configurationLoaded": true,
  "hubConnected": true,
  "mode": "advanced",
  "lastHubCommunication": "2026-10-12T09:45:41Z",
  "lastSensorExecution": "2026-10-12T09:45:38Z",
  "sensorExecutions": 4127
}

Champ	Signification
`mode`	`advanced` pour un agent Advanced, `standard` pour un agent Core.
`hubConnected`	La connexion avec le Hub est établie.
`lastHubCommunication`	Dernier échange avec le Hub.
`lastSensorExecution`, `sensorExecutions`	Dernier contrôle exécuté, et nombre de contrôles depuis le démarrage.

Les endpoints ne renvoient ni jeton, ni adresse, ni configuration. Les appeler souvent ne coûte rien : ils ne contactent jamais le Hub.

Réglages#

Variable	Défaut	Rôle
`PORT`	`8080`	Port d'écoute.
`HTTP_API_BIND`	`loopback`	`loopback` : uniquement depuis la machine elle-même (127.0.0.1). `any` : depuis partout — nécessaire pour les sondes venant de l'extérieur d'un conteneur. Ou une adresse IP précise.
`HTTP_API`	activé	`0` désactive les endpoints.

Par défaut, rien n'est exposé sur le réseau. Avec HTTP_API_BIND=any, gardez le port fermé vers l'extérieur : les endpoints ne servent qu'à la supervision.

Les endpoints démarrent une fois que l'agent s'est authentifié auprès d'Onagre. Avant cela — API injoignable, jeton erroné — ils ne répondent pas : lisez plutôt le log de l'agent. Si le port est déjà pris, l'agent journalise un avertissement et continue la surveillance.

Exemples#

Terminal

docker run -d --name onagre-agent --restart=always \
  --env-file ./onagre-agent.env \
  --health-cmd "curl -fsS http://127.0.0.1:8080/health || exit 1" \
  --health-interval 30s \
  onagreio/agent

YAML

env:
  - name: HTTP_API_BIND
    value: "any"
livenessProbe:
  httpGet: { path: /health, port: 8080 }
  periodSeconds: 30
readinessProbe:
  httpGet: { path: /ready, port: 8080 }
  periodSeconds: 30

Terminal

curl -s http://127.0.0.1:8080/status

Dépannage#

Symptôme	Cause probable
Connexion refusée	L'agent n'est pas encore démarré, attend encore l'API, ou son jeton a été refusé — lisez son log. Ou les endpoints sont désactivés (`HTTP_API`) ou sur un autre `PORT`.
`/ready` reste à `503` — `Hub stream not established`	Le Hub est injoignable sur le port 443 (pare-feu, proxy), ou un autre agent utilise déjà ce jeton.
`lastHubCommunication` est ancien	La connexion est tombée : l'agent se reconnecte de lui-même ; vérifiez le chemin réseau.