Contrôles de santé

OxPHP exécute un serveur HTTP interne sur un port distinct pour la surveillance de la santé, la collecte de métriques et l'inspection de la configuration. Il reste isolé du trafic applicatif, si bien que la surveillance n'entre jamais en concurrence avec les requêtes des utilisateurs.

Configuration

Définissez INTERNAL_ADDR pour activer le serveur interne :

bash

INTERNAL_ADDR=127.0.0.1:9090

Lorsque INTERNAL_ADDR n'est pas défini, le serveur interne ne démarre pas et aucun endpoint de santé n'est disponible.

Note

Un INTERNAL_ADDR réduit à un port (:9090 ou 9090) se lie à 127.0.0.1 ; utilisez un 0.0.0.0:9090 explicite pour exposer le serveur interne en dehors de l'hôte. Lorsqu'il est joignable en dehors de l'hôte, restreignez l'accès avec INTERNAL_ALLOW_IPS (une liste d'autorisation CIDR/IP — /metrics, /config et les chemins de plugins renvoient 403 aux pairs qui n'en font pas partie, tandis que les sondes de santé restent joignables) ; le loopback n'est pas implicite, indiquez donc 127.0.0.1/32 pour conserver l'accès depuis localhost. Le serveur émet un avertissement au démarrage si l'écouteur est exposé sans liste d'autorisation.

Sondes Kubernetes

OxPHP fournit des endpoints dédiés pour chaque type de sonde Kubernetes. Chaque endpoint est également disponible sous un alias court (/healthz, /readyz, /startupz).

Endpoint	Alias	Vérifie	200	503
`/health/liveness`	`/healthz`	Rien (vivant s'il répond)	Toujours	Jamais
`/health/readiness`	`/readyz`	Pas d'arrêt en cours, exécuteur sain, aucun plugin en échec	Prêt	Pas prêt
`/health/startup`	`/startupz`	Exécuteur sain	Prêt	Pas prêt

Liveness renvoie toujours 200 OK. Si le processus peut répondre à la requête HTTP, c'est qu'il est vivant. Aucune vérification de l'exécuteur ni des plugins n'est effectuée — cela empêche Kubernetes de redémarrer les pods à cause de problèmes transitoires du pool de workers.

Readiness renvoie 503 Service Unavailable lorsque :

Le serveur est en cours d'arrêt (arrêt gracieux en cours)
Le pool de workers PHP n'est pas sain
Un plugin signale une défaillance

Pendant l'arrêt gracieux, la sonde de readiness renvoie immédiatement 503, ce qui pousse Kubernetes à retirer le pod des endpoints du Service avant que le drainage ne se termine.

Startup renvoie 503 Service Unavailable tant que l'exécuteur n'est pas encore prêt. Utilisez cette sonde pour empêcher des arrêts prématurés dus à la sonde de liveness durant une initialisation lente.

Tous les endpoints de sonde renvoient Content-Type: text/plain avec le nom de la sonde comme corps de réponse (par exemple, readiness). Kubernetes n'inspecte que le code de statut HTTP.

bash

# Quick check
curl -s -o /dev/null -w '%{http_code}' http://localhost:9090/health/readiness

GET /health

Renvoie l'état de santé complet du serveur au format JSON. Utilisez-le pour les tableaux de bord et les systèmes de surveillance, pas pour les sondes Kubernetes.

bash

curl http://localhost:9090/health

Réponse saine (200 OK) :

json

{
  "status": "ok",
  "uptime_secs": 3612,
  "total_requests": 48203,
  "active_connections": 7,
  "executor_healthy": true,
  "plugins": {}
}

Réponse dégradée (503 Service Unavailable) :

json

{
  "status": "degraded",
  "uptime_secs": 3612,
  "total_requests": 48203,
  "active_connections": 7,
  "executor_healthy": false,
  "plugins": {}
}

Champ	Type	Description
`status`	string	`"ok"` lorsque tous les sous-systèmes sont sains, `"degraded"` sinon
`uptime_secs`	integer	Secondes écoulées depuis le démarrage du serveur
`total_requests`	integer	Nombre total de requêtes HTTP traitées sur le port principal
`active_connections`	integer	Connexions actuellement ouvertes sur le port principal
`executor_healthy`	boolean	Indique si le pool de workers PHP accepte les requêtes
`plugins`	`object<string, string>`	Santé par plugin : les clés sont les noms des plugins, les valeurs sont `"ok"`, `"degraded"` ou `"failed"`. `{}` vide lorsqu'aucun plugin ne rapporte de santé. Un plugin `"failed"` fait basculer le statut HTTP vers 503 ; `"degraded"` apparaît ici mais maintient le statut à 200.

GET /metrics

Renvoie des métriques compatibles Prometheus au format d'exposition texte. Consultez Métriques Prometheus pour la référence complète des métriques.

bash

curl http://localhost:9090/metrics

GET /config

Renvoie la configuration active du serveur au format JSON. Les chemins du certificat et de la clé TLS, internal_addr et error_pages_dir sont expurgés de la réponse pour des raisons de sécurité.

bash

curl -s http://localhost:9090/config | jq .

json

{
  "listen_addr": "0.0.0.0:80",
  "document_root": "/var/www/html/public",
  "entry_file": "/var/www/html/public/index.php",
  "log_level": "info",
  "executor_type": "sapi",
  "php_workers": "8",
  "tokio_workers": 4,
  "queue_capacity": 1024,
  "max_connections": 10000,
  "drain_timeout_seconds": 30,
  "header_timeout_seconds": 5,
  "rate_limit": 100,
  "rate_window_seconds": 60,
  "tls_enabled": true,
  "compression_level": 4,
  "access_log": "all",
  "max_query_body": 524288,
  "worker_mode_enabled": false,
  "worker_max_memory_mib": 0,
  "static_max_age": 2592000,
  "static_revalidate": false,
  "async_workers": 0,
  "async_queue_capacity": 0,
  "async_max_fibers": 256,
  "async_in_flight_cap": 0,
  "trace_context": false,
  "superglobals_enabled": true,
  "trusted_proxies": false,
  "plugins": {}
}

Note

Les chemins du certificat et de la clé TLS ne sont jamais émis (tls_enabled indique si TLS est actif), et internal_addr et error_pages_dir sont expurgés de la réponse servie.

Intégration Kubernetes

Utilisez des endpoints de sonde dédiés pour chaque type de sonde :

yaml

apiVersion: apps/v1
kind: Deployment
spec:
  template:
    spec:
      containers:
        - name: oxphp
          image: ghcr.io/oxphp/oxphp:latest
          env:
            - name: INTERNAL_ADDR
              value: "0.0.0.0:9090"
          ports:
            - containerPort: 8080
            - containerPort: 9090
          startupProbe:
            httpGet:
              path: /health/startup
              port: 9090
            initialDelaySeconds: 1
            periodSeconds: 2
            failureThreshold: 15
          livenessProbe:
            httpGet:
              path: /health/liveness
              port: 9090
            periodSeconds: 10
            failureThreshold: 3
          readinessProbe:
            httpGet:
              path: /health/readiness
              port: 9090
            periodSeconds: 5
            failureThreshold: 2

Sonde	Effet en cas d'échec
Startup	Kubernetes attend — ne tue pas le pod pendant l'initialisation
Liveness	Kubernetes redémarre le pod
Readiness	Kubernetes retire le pod des endpoints du Service (pas de redémarrage)

Les alias courts (/healthz, /readyz, /startupz) sont totalement équivalents et peuvent être utilisés à la place.

Contrôle de santé Docker Compose

compose.yaml

services:
  oxphp:
    image: ghcr.io/oxphp/oxphp:latest
    ports:
      - "8080:80"
    environment:
      INTERNAL_ADDR: "127.0.0.1:9090"
    healthcheck:
      test: ["CMD", "wget", "-qO-", "http://127.0.0.1:9090/health"]
      interval: 10s
      timeout: 5s
      retries: 3
      start_period: 5s

Docker marque le conteneur comme unhealthy après le nombre configuré d'échecs de tentatives, ce qui peut déclencher des politiques de redémarrage ou le retrait du répartiteur de charge.

Voir aussi

Métriques Prometheus — référence complète de toutes les métriques exposées
Arrêt gracieux — comment les sondes de santé interagissent avec le drainage lors de l'arrêt
Référence de configuration — toutes les variables d'environnement, y compris INTERNAL_ADDR