Kontrole stanu

OxPHP uruchamia wewnętrzny serwer HTTP na osobnym porcie na potrzeby monitorowania stanu, zbierania metryk i inspekcji konfiguracji. Pozostaje odizolowany od ruchu aplikacji, dzięki czemu monitoring nigdy nie konkuruje z żądaniami użytkowników.

Konfiguracja

Ustaw INTERNAL_ADDR, aby włączyć serwer wewnętrzny:

bash

INTERNAL_ADDR=127.0.0.1:9090

Gdy INTERNAL_ADDR nie jest ustawiony, serwer wewnętrzny się nie uruchamia i żadne endpointy kontroli stanu nie są dostępne.

Note

INTERNAL_ADDR zawierający tylko port (:9090 lub 9090) wiąże się z 127.0.0.1; użyj jawnego 0.0.0.0:9090, aby udostępnić serwer wewnętrzny poza hostem. Gdy jest osiągalny spoza hosta, ogranicz dostęp za pomocą INTERNAL_ALLOW_IPS (lista dozwolonych CIDR/IP — ścieżki /metrics, /config oraz ścieżki wtyczek zwracają 403 klientom spoza niej, natomiast sondy kontroli stanu pozostają osiągalne); pętla zwrotna nie jest domyślna, więc wpisz 127.0.0.1/32, aby zachować dostęp z localhost. Serwer ostrzega przy starcie, jeśli listener jest udostępniony bez ustawionej listy dozwolonych.

Sondy Kubernetes

OxPHP udostępnia dedykowane endpointy dla każdego typu sondy Kubernetes. Każdy endpoint jest również dostępny pod krótkim aliasem (/healthz, /readyz, /startupz).

Endpoint	Alias	Sprawdzenia	200	503
`/health/liveness`	`/healthz`	Brak (żywy, jeśli odpowiada)	Zawsze	Nigdy
`/health/readiness`	`/readyz`	Nie w trakcie zamykania, executor sprawny, brak nieudanych wtyczek	Gotowy	Niegotowy
`/health/startup`	`/startupz`	Executor sprawny	Gotowy	Niegotowy

Liveness zawsze zwraca 200 OK. Jeśli proces jest w stanie odpowiedzieć na żądanie HTTP, jest żywy. Nie są wykonywane żadne sprawdzenia executora ani wtyczek — zapobiega to restartowaniu podów przez Kubernetes z powodu przejściowych problemów z pulą workerów.

Readiness zwraca 503 Service Unavailable, gdy:

serwer jest w trakcie zamykania (trwa łagodne zamknięcie)
pula workerów PHP jest niesprawna
którakolwiek wtyczka zgłasza awarię

Podczas łagodnego zamknięcia readiness natychmiast zwraca 503, co powoduje, że Kubernetes usuwa pod z endpointów Service, zanim zakończy się drenaż połączeń.

Startup zwraca 503 Service Unavailable, gdy executor nie jest jeszcze gotowy. Użyj tej sondy, aby zapobiec przedwczesnemu zabijaniu przez liveness podczas wolnej inicjalizacji.

Wszystkie endpointy sond zwracają Content-Type: text/plain z nazwą sondy w treści (np. readiness). Kubernetes analizuje jedynie kod statusu HTTP.

bash

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

GET /health

Zwraca pełny stan serwera w formacie JSON. Używaj tego endpointu w dashboardach i systemach monitorowania, a nie do sond Kubernetes.

bash

curl http://localhost:9090/health

Odpowiedź w stanie sprawnym (200 OK):

json

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

Odpowiedź w stanie pogorszonym (503 Service Unavailable):

json

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

Pole	Typ	Opis
`status`	string	`"ok"`, gdy wszystkie podsystemy są sprawne, w przeciwnym razie `"degraded"`
`uptime_secs`	integer	Liczba sekund od uruchomienia serwera
`total_requests`	integer	Łączna liczba żądań HTTP przetworzonych na porcie głównym
`active_connections`	integer	Aktualnie otwarte połączenia na porcie głównym
`executor_healthy`	boolean	Czy pula workerów PHP przyjmuje żądania
`plugins`	`object<string, string>`	Stan poszczególnych wtyczek: klucze to nazwy wtyczek, a wartości to `"ok"`, `"degraded"` lub `"failed"`. Puste `{}`, gdy żadna wtyczka nie zgłasza stanu. Wtyczka `"failed"` powoduje przełączenie statusu HTTP na 503; `"degraded"` pojawia się tutaj, ale utrzymuje status na 200.

GET /metrics

Zwraca metryki zgodne z Prometheusem w tekstowym formacie ekspozycji. Pełny wykaz metryk znajdziesz w Metryki Prometheus.

bash

curl http://localhost:9090/metrics

GET /config

Zwraca aktywną konfigurację serwera w formacie JSON. Ścieżki do certyfikatu i klucza TLS, internal_addr oraz error_pages_dir są usuwane z odpowiedzi ze względów bezpieczeństwa.

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

Ścieżki do certyfikatu i klucza TLS nigdy nie są emitowane (tls_enabled wskazuje, czy TLS jest aktywny), a internal_addr oraz error_pages_dir są usuwane z serwowanej odpowiedzi.

Integracja z Kubernetes

Użyj dedykowanych endpointów sond dla każdego typu sondy:

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

Sonda	Efekt przy niepowodzeniu
Startup	Kubernetes czeka — nie zabija poda podczas inicjalizacji
Liveness	Kubernetes restartuje pod
Readiness	Kubernetes usuwa pod z endpointów Service (bez restartu)

Krótkie aliasy (/healthz, /readyz, /startupz) są w pełni równoważne i można ich użyć zamiennie.

Kontrola stanu w 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 oznacza kontener jako unhealthy po nieudanej skonfigurowanej liczbie ponownych prób, co może wyzwolić polityki restartu lub usunięcie z load balancera.

Zobacz też

Metryki Prometheus — pełny wykaz wszystkich udostępnianych metryk
Łagodne zamknięcie — jak sondy kontroli stanu współdziałają z drenażem podczas zamykania
Dokumentacja konfiguracji — wszystkie zmienne środowiskowe, w tym INTERNAL_ADDR