ヘルスチェック

OxPHP は、ヘルスモニタリング、メトリクス収集、設定確認のために、別ポートで内部 HTTP サーバーを実行します。このサーバーはアプリケーショントラフィックから隔離されているため、モニタリングがユーザーリクエストと競合することはありません。

セットアップ

INTERNAL_ADDR を設定すると内部サーバーが有効になります。

bash

INTERNAL_ADDR=127.0.0.1:9090

INTERNAL_ADDR が設定されていない場合、内部サーバーは起動せず、ヘルスチェックエンドポイントは一切利用できません。

Note

ポートのみを指定した INTERNAL_ADDR（:9090 または 9090）は 127.0.0.1 にバインドされます。内部サーバーをホスト外に公開するには、明示的に 0.0.0.0:9090 を指定してください。ホスト外から到達可能にする場合は、INTERNAL_ALLOW_IPS（CIDR/IP の許可リスト）でアクセスを制限してください。許可リストの範囲外のピアに対しては /metrics、/config、およびプラグインのパスが 403 を返しますが、ヘルスプローブは引き続き到達可能なままです。ループバックは暗黙的に許可されないため、localhost からのアクセスを維持するには 127.0.0.1/32 を列挙してください。許可リストを設定せずにリスナーが公開されている場合、サーバーは起動時に警告を出します。

Kubernetes プローブ

OxPHP は、各 Kubernetes プローブタイプ専用のエンドポイントを提供します。各エンドポイントは短いエイリアス（/healthz、/readyz、/startupz）でも利用できます。

エンドポイント	エイリアス	チェック内容	200	503
`/health/liveness`	`/healthz`	なし（応答すれば生存）	常に	一度もなし
`/health/readiness`	`/readyz`	シャットダウン中でない、executor が正常、失敗したプラグインがない	準備完了	準備未完了
`/health/startup`	`/startupz`	executor が正常	準備完了	準備未完了

Liveness は常に 200 OK を返します。プロセスが HTTP リクエストに応答できれば、生存していると見なされます。executor やプラグインのチェックは行われません。これにより、一時的なワーカープールの問題が原因で Kubernetes がポッドを再起動してしまうのを防ぎます。

Readiness は次の場合に 503 Service Unavailable を返します。

サーバーがシャットダウン中である（グレースフルシャットダウンの進行中）
PHP ワーカープールが正常でない
いずれかのプラグインが障害を報告している

グレースフルシャットダウン中、readiness はただちに 503 を返し、これによりドレインが完了する前に Kubernetes がポッドを Service エンドポイントから取り除きます。

Startup は executor がまだ準備できていない場合に 503 Service Unavailable を返します。このプローブを使うと、初期化が遅い間に liveness による早すぎる強制終了を防げます。

すべてのプローブエンドポイントは Content-Type: text/plain を返し、ボディにはプローブ名（例: readiness）が入ります。Kubernetes は HTTP ステータスコードのみを参照します。

bash

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

GET /health

サーバー全体のヘルス状態を JSON で返します。Kubernetes プローブではなく、ダッシュボードやモニタリングシステムで使用してください。

bash

curl http://localhost:9090/health

正常時のレスポンス（200 OK）:

json

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

劣化時のレスポンス（503 Service Unavailable）:

json

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

フィールド	型	説明
`status`	string	すべてのサブシステムが正常なとき `"ok"`、それ以外は `"degraded"`
`uptime_secs`	integer	サーバー起動からの経過秒数
`total_requests`	integer	メインポートで処理した HTTP リクエストの総数
`active_connections`	integer	メインポートで現在オープンしている接続数
`executor_healthy`	boolean	PHP ワーカープールがリクエストを受け付けているかどうか
`plugins`	`object<string, string>`	プラグインごとのヘルス状態。キーはプラグイン名、値は `"ok"`、`"degraded"`、`"failed"` のいずれか。ヘルスを報告するプラグインがない場合は空の `{}`。`"failed"` のプラグインがあると HTTP ステータスは 503 に切り替わります。`"degraded"` はここに表示されますが、ステータスは 200 のまま保たれます。

GET /metrics

Prometheus 互換のメトリクスをテキスト公開フォーマットで返します。すべてのメトリクスの完全なリファレンスは Prometheus メトリクスを参照してください。

bash

curl http://localhost:9090/metrics

GET /config

有効なサーバー設定を JSON で返します。TLS 証明書と鍵のパス、internal_addr、error_pages_dir は、セキュリティ上の理由からレスポンスから除去されます。

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

TLS 証明書と鍵のパスは一切出力されません（TLS が有効かどうかは tls_enabled が示します）。また internal_addr と error_pages_dir は返されるレスポンスから除去されます。

Kubernetes との統合

各プローブタイプには専用のプローブエンドポイントを使用してください。

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

プローブ	失敗時の挙動
Startup	Kubernetes は待機します。初期化中はポッドを強制終了しません
Liveness	Kubernetes はポッドを再起動します
Readiness	Kubernetes はポッドを Service エンドポイントから取り除きます（再起動はしません）

短いエイリアス（/healthz、/readyz、/startupz）は完全に同等であり、代わりに使用できます。

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 はコンテナを unhealthy としてマークします。これにより再起動ポリシーやロードバランサーからの除外がトリガーされることがあります。

ヘルスチェック

セットアップ

Kubernetes プローブ

GET /health

GET /metrics

GET /config

Kubernetes との統合

Docker Compose のヘルスチェック

関連情報