Prometheus メトリクス

OxPHP は、内部サーバーの GET /metrics で Prometheus 互換のメトリクスをテキスト表示形式（text exposition format）で公開します。これらのメトリクスは、リクエストのスループット、レスポンスタイム、コネクションの状態、ワーカープールの健全性、静的ファイルのキャッシュ、圧縮効率、ワーカーモードのパフォーマンスをカバーします。

メトリクスの有効化

内部サーバーを起動するには INTERNAL_ADDR を設定します。

その後、Prometheus または任意の互換コレクターからスクレイプします。

サーバーメトリクス

リクエストメトリクス

リクエスト処理時間のヒストグラム

バケットの境界値（マイクロ秒）: 100, 500, 1000, 2500, 5000, 10000, 25000, 50000, 100000, 250000, 500000, 1000000, +Inf。

このヒストグラムを使って、全体のレイテンシーを追跡し、遅いエンドポイントを特定し、テールレイテンシーのパーセンタイルを測定できます。

コネクションメトリクス

キューの深さを受け入れスロットと照らし合わせて読む

2 つのゲージは 1 つの問いの別々の半分に答えます。その問いとは、キューがどれだけ深いかではなく、何かが動いているかどうかです。oxphp_queue_depth は何が待っているかを、oxphp_admission_slots_available はさらに何かを受け入れられるかを示します。どちらも oxphp_busy_workers と照らし合わせて読んでください。

最後の 3 行は、停止したプールが取る形です。いずれの場合も、PHP リクエストが 1 つも完了しないのに、それ以外の様子は健全に見えます。ビジーなワーカーはおらず、liveness は終始、readiness は最初の 1 分間 200 を返し、静的ファイルは通常どおり配信されます。拒否カウンターは動きますが、通常の過負荷でも動きます。oxphp_pending_requests は詰まったキューとともに上昇し、到着したリクエストがそれぞれ自身の予算で応答されるにつれて下がるため、単独ではここで何の意味も持ちません。しかし oxphp_queue_depth と照らし合わせると意味を持ちます。pending がほぼゼロで深さが上限に張り付いているのは、詰まりがこれまでに与えられたすべてを抱え込んでいる状態です。

サーバー自身も詰まりに気づきます。1 秒ごとのスキャンが 2 回連続して、待っている作業（キュー内のリクエスト、または増え続ける拒否）があり、少なくとも 1 つのワーカーがアイドルで、プールが何も完了していないことを確認すると、次のログを出力します。

この状態が続く間はおよそ 1 分に 1 回繰り返され、作業が動き出すと INFO PHP pool is reaching workers again が続きます。フィールドは fields の下にあるため、アラートルールでは .queue_depth ではなく .fields.queue_depth を指定します。誤報を防ぐガードが 3 つあります。1 回ではなく 2 回のスキャンであること。進捗を、クライアントが受け取ったものではなくワーカーが完了したものとして測ること（そのためクライアントの中断が殺到しても、実際どおりビジーなプールとして読まれます）。そして、プールが最初のリクエストを完了するまでは何も報告しないこと（起動時のブートストラップを詰まりと取り違えないため）です。

最後のガードが対象とするのは、プロセスの最初のブートストラップだけです。後から（メモリ上限や Worker::scheduleExit() で）リサイクルされたワーカーはアプリケーションを再びブートし、最初のリクエストを受け取るまではアイドルとして読まれます。そのため、ワーカーが 1 つのプール（あるいは他のワーカーがすべてビジーな大きめのプール）でブートストラップが遅いと、偽の警告が 1 回出て、その後に回復の通知が出ます。同じ瞬間に oxphp_workers_spawned_total が動いていれば、それと判別できます。

この警告はワーカーモードでのみ出力されます。ワーカーが完了したものを数えているのはそのプールだけだからです。ワーカーがキュー自体でブロックするモードでは、この警告が表す状態は起こりえません。3 つのゲージはすべてのモードで出力されます。

無駄になった待機

oxphp_admission_wait_wasted_total は、キューから離れたエントリーではなく開始された作業を数えます。期限で既に応答済みのリクエストをワーカーが片付けても、キューは動きますが誰にもサービスしていないからです。予算が上限にあることを条件にしているのは、サーバーが予算を短縮した後では「プールが何も開始しなかった」がプールよりも時間枠について多くを語るためです。4 ワーカーの健全なプールが 0.25 秒のハンドラーを処理すると 62 ms ごとに 1 件リクエストを開始するので、下限ではほとんどの待機が 2 回の開始の間で終わってしまいます。

この条件によって失われるものは、予算が動くかどうかで決まります。

• 何も開始しないプールは、コントローラーが判断の基準とする開始リクエスト数に決して達しないため、上限を保ち、このカウンターは有効なままです。
• 自分自身を呼び出すプールは、外側のリクエストが内側の呼び出しを諦めるたびにリクエストを開始します。自分の呼び出し元がハンドラーより辛抱強くなくなると予算は下がり（数秒以内に 2 回半減したことが測定されています）、このカウンターは下がる前の到着分が終わると静かになります。そこではこのページのどれも代わりを務めません。アプリケーション自身の外向き呼び出しの中からそのパターンを見つけてください。呼び出し元が辛抱強い場合（内部の cron や、タイムアウトに余裕のあるサイドカー）、誰も去らないので上限はそのまま保たれ、このカウンターがそれを示すものになります。

典型的な原因は、アプリケーションが HTTP 経由でこの同じサーバーを呼び返すことですが、このカウンターは自己呼び出しの検出器ではありません。すべてのハンドラーが予算より長く実行されるプールも、待機の間に何も空けないからです。ワーカーモードでは oxphp_worker_request_duration_us（ハンドラーの時間。キュー待機は除く）で両者を区別できます。このカウンターが増えているのにハンドラーが予算を下回っているなら、待機は単に遅い処理の後ろに並んでいるだけではありません。これに oxphp_request_duration_us を使わないでください。これらの拒否を含んでおり、それぞれがほぼ予算まるごと分を加えるからです。ワーカーモード以外では、アプリケーション自身の計測値を使ってください。

QUEUE_WAIT_TIMEOUT_MS=0 は、短い予算をさらに短くしたものではありません。キューのスロットを待つ時間をなくすだけで、キューの中での待機は無制限のままにします。そのため、何も取り出さないプールでは、空きスロットを見つけたリクエストは決して応答されません。0 を使うなら、問題になる頃にはキューが満杯になっている程度に小さな QUEUE_CAPACITY と組み合わせてください。

リクエストを切り捨てている間のログ

スーパーバイザーは同じ 1 秒ごとのスキャンで oxphp_admission_refused_total の過負荷を示す 4 つの理由を監視し、個々のリクエストではなくエピソードを報告します。拒否ごとに 1 行出していたら、それ自体が障害になるからです。いずれかが動いたのを最初に確認したスキャンは次のログを出力します。

refused はそのスキャン 1 回で拒否した数です。ただし、確認できるキューがある最初のスキャンだけは、それ以前に切り捨てたものすべてを報告します（到着が積み上がる中でまだアプリケーションを読み込んでいるプールも、本物のエピソードです）。深さが上限に達して空きスロットがないのは処理が遅れているプールであり、wait_budget_us が wait_budget_ceiling_us を大きく下回っていれば、サーバーが既に待機を短縮していることを示します。両方の数値があるのは、下限まで押し下げられた予算と、そこまで低く設定された予算とは、単独では見分けがつかないからです。キューの数値はスキャン時点のスナップショットで、refused は直前の 1 秒をカバーしているため、空のキューの横に大きな refused があるのは短いバーストであって、矛盾ではありません。

どちらの数も、oxphp_admission_refused_total の過負荷を示す 4 つのラベルによって理由別に内訳が示され、フィールド名は内訳の元になる数の名前から作られます。refused_queue_full、refused_wait_timeout、refused_waiting_full、refused_waiting_bytes の合計が refused になり、後述の繰り返しの警告と締めくくりの行には episode_refused_queue_full とそれに並ぶ 3 つのフィールドが含まれ、その合計が episode_refused になります。どの設定を調整すべきかを決めるのは理由であり（それぞれが何を示すかは上のカウンターの行を参照してください）、そのカウンターは INTERNAL_ADDR でしか提供されません。内部リスナーのないインスタンスでは、これらのフィールドと、トレーシングが有効な場合の oxphp.shed_reason スパン属性が、理由を読み取れる場所として残ります。4 つすべてが 0 であっても出力されます。明示的な 0 こそが、その理由を除外する根拠になるからです。

エピソードが続く間、警告は PHP admission is still shedding requests under overload として繰り返されます。頻度は多くても 1 分に 1 回で、それ自体が拒否しているスキャンでのみ出る（そのため間隔は 2 分近くになることもあります）ほか、スキャンごとの refused と並んで episode_refused（累計）を含みます。繰り返しの警告が理由別の内訳を示すのは、そのスキャンの数ではなくエピソードの累計です。これが重要なのは、締めくくりの行が INFO で書き出され、本番向けの設定が使うログレベル warn より低いためです。そうした環境では、繰り返しの警告が、書き出されたスキャンの時点までにエピソードが何で構成されていたかを示す唯一の行になります。最初の 1 分以内に終わるエピソードには繰り返しの警告がまったくなく、最後の繰り返しより後に拒否されたものは締めくくりの行にしか現れません。拒否のない 1 分でエピソードは終わり、INFO で出力されます。

duration_ms はこの行までではなく最後の拒否までの時間なので、締めくくりの静かな 1 分は含まれません。静かな 1 分という条件は、1 分より短い間隔が 1 つのエピソードにまとめられることも意味し、それによって出力は最悪でも 1 分に 2 行に抑えられます。開始にはそのような遅延はありません。拒否はサンプルではなく事実だからです。

この報告はすべてのルーティングモードで出力され、過負荷を示す 4 つの理由だけで動くため、再起動（shutting_down）やプールの消滅（pool_unavailable）が負荷として告げられることはありません。この状態を表すゲージはなく、どのプローブにも伝えられません。切り捨てによって /health/readiness の応答が変わることはありません。529 を切り捨てているインスタンスは、正常に動くプールで素早く応答しているのであり、過負荷のレプリカを順番にローテーションから外していけば、Service にはエンドポイントが 1 つも残らなくなるからです。過負荷には容量の追加で対処してください。詰まったプールも切り捨てを行い、ワーカーモードではその状態が 1 分続くと 503 を返します。両者はキューで区別できます。単に遅れているプールはキューを空にしていきますが、詰まったプールは空にしません。

ワーカープールメトリクス

ワーカースーパーバイザーメトリクス

ワーカースーパーバイザーが出力するワーカーごとのオブザーバビリティです。各系列は worker_id ラベル（スロットのインデックス）を持ちます。これらはスーパーバイザーがワーカーごとの状態を追跡し始めると出力されます。

キュー待機時間のヒストグラム

バケットの境界値（マイクロ秒）: 50, 100, 250, 500, 1000, 2500, 5000, 10000, 50000, 100000, 250000, 500000, 1000000, +Inf。

これはワーカーがリクエストをキューから取り出す瞬間までの、待機に費やされた時間（受け入れ待ち、次いでキュー内）を測るものです。つまり「リクエストにどれだけ時間がかかったか」ではなく「ワーカーが取り出すまでどれだけかかったか」に答えます。その瞬間より後のものは含まれません。ワーカーによるリクエストの準備、スクリプト（ストリームレスポンスではレスポンスヘッドまで）、そしてサーバーの I/O スレッドへのレスポンスの受け渡しは、すべて oxphp_request_duration_us に計上されます。この受け渡しはタダではありません。レスポンスは I/O スレッドが起こされるのを、あるいはその前に積まれた作業が片付くのを待つため、軽いスクリプトではこの待機より後の時間がスクリプト自身の実行時間の数倍になることがあります。

ここに記録されるのは、予算内にワーカーがキューから取り出したリクエストだけです。過負荷で拒否された 529、あるいはサーバーのシャットダウン中やプールの消滅時の 503/500 は oxphp_admission_refused_total にカウントされます。ワーカーが到達する前にクライアントが去った場合の 499 は oxphp_request_cancelled_total{reason="client_abort"} にカウントされ、どの拒否系列にも入りません。

キュー待機時間が長いのは、リクエストがワーカーに届くまでに時間がかかったことを意味しますが、それだけでワーカー不足を意味するわけではありません。どの測定値にも、渡されたリクエストにワーカースレッドが取りかかるまでの時間が含まれており、それは負荷のないサーバーでも存在します。PHP_WORKERS を増やす前に、リクエストがすべてのワーカーがビジーな状態に行き当たっていること、そしてマシンに余っているコアがあることを確認してください。サーバー自身の I/O スレッド、他のプロセス、コンテナの CPU クォータがワーカーと競合します。oxphp_busy_workers と oxphp_workers_current の比較は前者に部分的にしか答えません。スクレイプ時点で読まれるため、スクレイプの間にプールを埋めたバーストはここには現れてもそこには現れず、ワーカーモードではスレッドは何らかのリクエストを抱えている間、そのリクエストのハンドラーが中断されてスレッドが他を引き受けている間でさえ、ビジーとカウントされます。レンジはデフォルトの QUEUE_WAIT_TIMEOUT_MS に合わせて 1 秒まで達するため、実行前に待機予算の大半を費やしたリクエストも +Inf にまとめられるのではなく定量化されます。処理されるリクエストが予算より長く待つことはありません（予算を超えたリクエストは拒否されます）ので、待機を再び +Inf へ押し込む唯一の設定は QUEUE_WAIT_TIMEOUT_MS の引き上げです。

レート制限メトリクス

静的ファイルキャッシュメトリクス

圧縮メトリクス

ワーカーモードメトリクス

これらのメトリクスはワーカーモードが有効な場合（WORKER_MODE_ENABLED=true）のみ出力されます。

グローバルカウンター

ワーカーごとのゲージ

ワーカーリクエスト処理時間のヒストグラム

バケットの境界値（マイクロ秒）: 100, 250, 500, 1000, 2500, 5000, 10000, 25000, 50000, +Inf。

このヒストグラムは、キュー待機時間を除いた、PHP ハンドラーコールバック内で費やされた時間を測定します。遅いハンドラーを特定し、ワーカーモードでのテールレイテンシーを追跡するために使用します。

非同期プールメトリクス

これらのメトリクスには ASYNC_WORKERS に 0 以外の値を設定する必要があり、それぞれに独自の出力条件があります。カウンターは少なくとも 1 つのタスクがディスパッチまたは拒否された後にのみ出力され、_in_flight / _in_flight_limit のゲージはプールが処理中カウンターを初期化した時点で出力され、oxphp_async_output_discarded_bytes_total は一部の出力が破棄された後にのみ出力されます。

OpenTelemetry エクスポートメトリクス

これらのメトリクスには OTEL_ENABLED=true が必要です。OxPHP が OTLP コレクターに送信するスパンのバッチをカウントします。対象はリクエストのスパンと、APM プラグインが有効な場合は APM のスパンです。

エクスポートは、最初の試行が OTEL_EXPORTER_OTLP_TIMEOUT の半分と 1 秒のいずれか短いほうの時間内に、コレクターからの応答なしに失敗した場合、つまり接続がリセットまたはクローズされたか、接続を確立できなかった場合に、1 回リトライされます。よくある原因は、エクスポートの合間にアイドル状態だった接続をロードバランサーや NAT が切断したことです。API キーの拒否やスロットリングなど、コレクターが応答として返したエラーステータスはリトライされません。OTLP 仕様がその大半のリトライを禁じており、またエクスポーターは、スロットリング中のコレクターが求める待機時間を引き継がないからです。バッチを届けたリトライは oxphp_otel_export_retries_total にのみカウントされます。エクスポートのタイムアウトに達した試行はリトライされないため、遅いコレクターに同じバッチが 2 回送られることはありません。

ただし、リトライによって重複が生じることはあります。接続が切れる前にコレクターが最初の試行を受信していた場合、リトライはそれらのスパンを 2 回目として届けます。同じ理由で、失敗としてカウントされたエクスポートが実際にはコレクターに届いていることもあります。

キューが満杯であるためにトレーサーがエクスポート前に破棄したスパン（OTEL_BSP_MAX_QUEUE_SIZE、デフォルトは 2048 スパン）は、ここではカウントされません。

Grafana ダッシュボードのヒント

以下の PromQL クエリはダッシュボードの構築に役立ちます。

リクエストレート（1 秒あたりのリクエスト数）:

平均レスポンスタイム（ミリ秒）:

p99 リクエスト処理時間（ミリ秒）:

エラーレート（5xx レスポンスの割合）:

ワーカープールの使用率:

これは 0 から 1 の間の真の比率です。1 に張り付いた値が続く場合、すべてのワーカーが占有されており、以降の到着はキューイングされています。rate(oxphp_admission_refused_total{reason=~"queue_full|wait_timeout|waiting_full|waiting_bytes"}[5m]) と組み合わせてそのバックログが拒否に転じているかを、oxphp_pending_requests と組み合わせてその深さを確認してください。

キューの飽和（1 秒あたりのドロップレート）:

p99 キュー待機時間（マイクロ秒）:

静的ファイルキャッシュのヒット率:

1 秒あたりの圧縮による節約バイト数:

ワーカーモードの p99 レイテンシー（マイクロ秒）:

上限を下回るまで押し下げられた待機予算（比率）:

1 が正常です。それより低い値は、サーバーが過負荷の下で待機を短縮していることを意味します。QUEUE_WAIT_TIMEOUT_MS から写した数値ではなく、この比率でアラートを設定してください。

accept ループの停止（0 以外でアラート）:

ワーカーのリサイクルレート（1 分あたり）:

ワーカーの平均メモリ使用量:

Prometheus のスクレイプ設定

prometheus.yml にスクレイプジョブを追加します。

Kubernetes のサービスディスカバリを使う場合:

エージェント向けプロンプト

これらのプロンプトは、OxPHP ドキュメント MCP サーバー を接続したエージェントを前提としています — 必要なページはエージェントが自分で読み取ります。

関連情報

• ヘルスチェック — 内部サーバーの /health および /config エンドポイント
• 設定リファレンス — INTERNAL_ADDR を含むすべての環境変数
• グレースフルシャットダウン — コネクションのドレインが oxphp_active_connections に与える影響
• ワーカーモード — 永続ワーカーとそれが出力するメトリクス