phpray

PHPRay

PHP のすべてのリクエストを記録します。どのプラグインが、どのクエリが、いつから問題なのかを確認できます。

PHPRay は、PHP のリクエストを常時トレースします。サンプルではなく、すべてのリクエストについて、実行時間、CPU、メモリ、SQL、外部への HTTP 通信、エラー、N+1 パターンを記録し、一部のリクエストではプラグイン／コンポーネントごとの時間内訳も追加します。1 つのサイトでも、クライアントのサイトが 100 個でも、同じ方法でインストールでき、すべてを 1 つの一覧で確認できます。

PHP 拡張機能とローカルコレクターで構成されています。root 権限を必要とするエージェントはなく、PHP プロセスからのネットワーク通信もなく、SaaS アカウントも不要です。共有ホスティング（CageFS、LiteSpeed lsphp、mod_php）、VPS、コンテナで動作し、PHP 8.0–8.5、glibc と musl、amd64 と arm64 に対応しています。

curl -fsSL https://phpray.dev/install.sh -o phpray-install.sh
less phpray-install.sh          # it asks for root; read it first
sudo bash phpray-install.sh && phpray top

数分間トラフィックを記録した後、phpray report --domain example.com --share を実行すると、クライアントに送れるリンクが表示されます。サイト名は削除され、リンクには有効期限があり、閲覧する相手は何もインストールする必要がありません。

何もインストールせずに、まず見てみたいですか？ root 権限、アカウント、カードがなくても利用できる方法が 3 つあります。

• 本番環境の WooCommerce ストアの実際のレポート — サイト名を削除した HTML ファイル 1 つです。これはモックアップではなく、実際の出力です。
• 実際のトラフィックを表示するコンソール — 読み取り専用で、登録不要です。
• エージェントから接続：claude mcp add --transport http phpray https://phpray.dev/mcp で、キーなしで同じデモデータから応答します（詳細）。

表示例

PHPRay Cloud：すべてのサイトから、1 つのサイト、さらに PHP とデータベースの所要時間、処理にかかったプラグイン、その背後にあるクエリに分解された、887 ms のリクエストまでを表示します。デモデータです。

解決する疑問

「先週、ストアの動作が遅くなった」だけでは、対処につながりません。PHPRay は、問題のプラグイン名、クエリ名、変化した日付を特定します。

複数のサイトを管理している場合

上記の大半は、1 台のサーバーについての説明です。より難しいのは、もう 1 つの仕事です。自分が構築したのではなく、ホスティング環境も選べない 40 のサイトを管理しながら、今日チェックアウトが遅い理由をクライアントに聞かれることです。

• 40 個のパネルではなく、1 つの一覧。 すべてのサイトを 1 つのコンソールにまとめ、リクエスト、p95、エラー率、データベースの割合を表示し、現在問題が起きている順に並べます。そこからワンクリックで個別のリクエストを確認できます。ライブデモでは、1 つの代理店が管理する 10 サイトを、アカウント不要の読み取り専用で表示しています。
• クライアントが実際に利用している環境にインストールできます。 root 権限のない共有ホスティングでは、アカウントごとにインストールできます。拡張機能は各アカウント自身の php.ini から読み込むか、WordPress プラグインを拡張機能やデーモンなしで動作させられます。共有サーバーでは、PHP バージョン全体に対して拡張機能を有効にしないでください。アカウントごとにインストールしてください。
• クライアントに送れるレポート。 phpray report -domain shop.example -share を実行すると、調査結果を公開し、リンクを表示します。サイト名は削除され、リンクは期限切れになり、インデックスには登録されません。アカウントもカードも不要です。
• ホスティングプロバイダー向け。 すべてのアカウントを確認できる管理者ビューと、顧客用のユーザービューを備えた DirectAdmin プラグインに加え、セルフホスト可能なコンソールを用意しています。Host Editionをご覧ください。

ローカルコアは Apache-2.0 のままで、制限はありません。サイト、サーバー、リクエストをいくつでも利用でき、データはご自身のディスクに保存されます。有料なのは、サイトを 1 つの一覧にまとめるホスト型コンソールです。料金は登録するサイト数に応じて決まり、1 サイトから無料で利用できます。料金はphpray.dev/en/pricingをご覧ください。

別のプロファイラーが必要な理由

• サンプリングではなく、すべてのリクエストを記録します。 サンプリング型のエージェントは、サンプル間の統計情報を保持します。 PHPRay はリクエストごとに 1 件のレコードを書き込むため、失敗した唯一のチェックアウトや、一度だけ発生したエラーも、調べるときに記録に残っています。
• 常時有効にしておけるほど低負荷で、その負荷を測定済みです。 48 ms でレンダリングされる WordPress ページでは、関数オブザーバーをオフにしたトレースは、5 回の交互実行を通してベースラインとの差を確認できませんでした。現在のデフォルトであるオブザーバーをオンにすると、ページの処理時間は 50 ms でした。手法、生の数値、注意点については、 ベンチマークをご覧ください。Xdebug はすべての関数呼び出しを計測するため、意図的に有効にする必要があります。
• 負荷の高い処理は、意図的にサンプリングしています。 関数ごとのプロファイリングは、デフォルトでリクエストの 3 % に対して実行されます。本番トラフィックのすべてのリクエストについて、すべての呼び出しを測定すると、トラフィック自体よりもコストがかかります。ただし、正直にお伝えすべき注意点があります。これを可能にするオブザーバーはすべてのリクエストに対して登録されるため、上記の 2 ms の負荷が発生します。常時有効なレイヤーの負荷を可能な限り抑えたい場合は phpray.profile_functions=0 を設定し、調査時のみ内訳を有効にしてください。
• 共有ホスティング向けに構築されており、自分でインストールできます。 システムリソースを占有するデーモンも、エージェントのバイナリも必要ありません。この拡張機能は、共有メモリまたは通常のファイルを使ってローカルコレクターと通信します。自身の php.ini を編集できるホスト（cPanel MultiPHP INI Editor、CloudLinux PHP Selector、Plesk など）であれば、ホームディレクトリ内の .so を extension= で指定し、コレクターを自身のユーザーとして実行できます。root 権限も、コンパイラーも、他人の許可も必要ありません。uid 1000 で最初から最後まで動作することを確認済みです。動作しないケースについては ドキュメントに記載しています。

開発元

数千のサイトで PHP を運用するヨーロッパのホスティングプロバイダー、IQhost が開発しています。PHPRay はそこで開発され、最初に導入されています。この README に記載されている共有ホスティング環境の制約は仮定上のものではなく、この拡張機能が日々乗り越えなければならない実際の環境です。

エージェントに遅い処理を尋ねる

PHPRay には MCP サーバーが付属しているため、コーディングエージェントがトレースを読み取り、ダッシュボードを開かなくても「このページを遅くしているプラグインはどれですか？」と答えられます。

インストールもアカウントもなしで試せます。実際の WooCommerce ストアで記録されたトラフィックを使える、読み取り専用のデモアカウントが利用できます。

claude mcp add --transport http phpray https://phpray.dev/mcp

次に、最も遅いページはどれか、最もコストのかかる SQL フィンガープリントはどれか、時間を最も消費しているプラグインはどれかを尋ねてください。--header "Authorization: Bearer <console token>" を追加すると、同じツールで自身のサイトを読み取れます。

または、stdio 経由でローカルのバイナリとして実行できます。

# pick your platform: linux-amd64, linux-arm64, darwin-amd64, darwin-arm64
curl -fsSL -o phpray-mcp "https://phpray.dev/dl/$(curl -fsS https://phpray.dev/dl/LATEST)/phpray-mcp-linux-amd64"
chmod +x phpray-mcp && sudo mv phpray-mcp /usr/local/bin/

# every server in one place, scoped to your console token
claude mcp add phpray --env PHPRAY_TOKEN=<console token> -- phpray-mcp

# or just this machine's collector, no account needed
claude mcp add phpray-local -- phpray-mcp

クラウドモードでは、トークンとしてコンソールトークンを使うため、エージェントにはそのトークンのスコープ内にあるサイトだけが表示されます。ローカルモードでは、同じマシン上のコレクターを読み取るため、アカウントは必要ありません。

読み取り専用ツールは 10 個 — サイト、概要、最も遅いページ、遅い SQL、コンポーネント別の内訳、エラー、トレース、単一トレースの全情報、変更前後の比較、アラート — に加えて、URL プレフィックスに対して関数ごとのプロファイリングを有効にする 11 個目の phpray_profile_url があります。このツールは状態を変更するため、公開デモエンドポイントでは提供されません。トークンなしの場合、tools/list は 10 個を返します。自身のコンソールトークンを使うか、stdio 経由でローカル実行すると、11 個すべてを利用できます。ソースとプロトコルに関するメモ： src/mcp/。

無料版と有料版

このリポジトリのすべてのものは Apache-2.0 ライセンスの下で無料かつオープンソースです。拡張機能、コレクター、CLI、ローカルダッシュボード、パネルプラグインが含まれます。単一のサーバーで、これだけで完結する製品として、いつまでも利用できます。

有料なのは PHPRay Cloud です。複数サーバーの一元管理、ディスク容量を超える履歴、アラート機能、ホスティングパネルのコンソールを提供します。これは独立したクローズドソースのコードベースです。自分でサーバーキーを設定しない限り、ここにあるものが PHPRay Cloud に情報を送信することはありません。

クイックスタート

curl -fsSL https://phpray.dev/install.sh -o phpray-install.sh
less phpray-install.sh
sudo bash phpray-install.sh
phpray status

インストーラーをそのまま root シェルにパイプするのは、避けるべき習慣です。私たちのものも例外ではありません。ダウンロードして内容を読み、それから実行してください。取得するすべてのファイルのチェックサムは、 https://phpray.dev/dl/<version>/SHA256SUMS に公開されており、インストーラーが検証します。

インストーラーはホスト上のすべての PHP バージョンを検出し、それぞれにビルド済みの phpray.so をインストールして、systemd ユニットとともにコレクターをデプロイし、PHP プールを再読み込みします。外部依存関係のない単一バイナリです。

手動インストール

各パーツを自分で配置する場合は、次の手順に従ってください。

# 1. drop the prebuilt extension into your PHP extension dir
sudo cp phpray.so /usr/local/lib/php/extensions/no-debug-non-zts-20240924/

# 2. enable it (Debian layout shown; use your distro's conf.d)
echo "extension=phpray.so" | sudo tee /etc/php/8.3/fpm/conf.d/99-phpray.ini
sudo systemctl reload php8.3-fpm

# 3. run the collector
sudo /usr/local/bin/phpray-collector serve -addr :9191

検証

php -m | grep phpray                       # "phpray" is listed
curl -sI https://yoursite.com              # X-PHPRay-ID: pr-... response header

CLI

phpray status        # extension loaded, collector running, recent volume
phpray top           # live slowest requests, htop-style
phpray trace         # per-request waterfall (queries, HTTP calls, components)
phpray diag shop.pl  # health score + findings + recommendations

誰かに送れるレポート

PHPRay をインストールしたことがない人が定期的に目にする、唯一の PHPRay 成果物です。代理店が店舗オーナーに送ったり、管理者がチケットに貼り付けたりします。

phpray report -domain shop.example -w 1440 -format html -o report.html
phpray report -domain shop.example -format html -anonymize -o public.html

ヘルススコア、検出内容、コスト、対処方法を含む、自己完結型の単一ファイルです。外部リクエスト、フォント、スクリプトはありません。-anonymize を指定すると、検出結果や証拠を含め、ドメインがすべての箇所で置き換えられるため、同じレポートをフォーラムや提案書に掲載できます。

共有されるのは添付ファイルではなくリンクなので、同じ検出結果をページとして公開することもできます。

phpray report -domain shop.example -w 60 -share
https://app.phpray.dev/r/dklns4bdbf74bdtetbxhbxtcey

アカウントもカードも不要です。このリポジトリのコレクターから利用できます。サーバーから送信されるのは検出結果のデータのみで、ドキュメントではありません。ページはそのデータから、私たちのテンプレートを使ってレンダリングされます。証拠の行も含め、すべてのテキストフィールドからサイト名が削除されるため、shop.example/checkout/ は /checkout/ として公開されます。アドレスには128ビットのランダム性があり、30日後に有効期限が切れ、インデックスにも登録されません。-share-url を指定すると、同じコマンドの送信先を自分のコンソールにできます。

トレースに含まれる内容

各リクエストから1つの JSON レコードが生成されます。関数プロファイルも記録されたリクエストには、"profiled": 1 と、コンポーネントごとの incl_ns、self_ns、calls を含む components 配列が含まれます。

{
  "ts": 1774713671,
  "host": "shop.example.com",
  "method": "GET",
  "uri": "/checkout",
  "status": 500,
  "duration_ms": 2411.7,
  "cpu_user_ms": 188.4,
  "memory_peak_mb": 96.2,
  "app": "wp",
  "level": "full",
  "db_count": 142,
  "queries": [
    { "sql": "SELECT * FROM wp_posts WHERE ID = ?", "ms": 12.4 }
  ],
  "http_calls": [
    { "url": "https://api.stripe.com/v1/checkout/sessions", "ms": 1842.9, "status": 200 }
  ],
  "errors": [
    { "type": "E_WARNING", "msg": "Division by zero", "file": "/wp-content/plugins/xyz/fee.php", "t": 1903.1 }
  ],
  "n1": 1,
  "profiled": 1,
  "components": [
    { "name": "plugins/woocommerce", "incl_ns": 1430221, "self_ns": 902114, "calls": 1874 },
    { "name": "themes/storefront",   "incl_ns": 612009,  "self_ns": 504002, "calls": 913 },
    { "name": "core",                "incl_ns": 421778,  "self_ns": 388001, "calls": 1204 }
  ]
}

incl_ns は、コンポーネント内で費やされた時間です（そのコンポーネントが呼び出すすべてのコアやその他の PHP を含みます）。self_ns はネストされたコンポーネントを除外した時間です。calls は、そのコンポーネントで観測された関数呼び出しの回数です。

設定

最もよく変更する6つのディレクティブです。PERDIR はサイトまたはディレクトリごとに上書きできることを意味し、SYSTEM は php.ini で設定する必要があることを意味します。

phpray.enabled            = 1        ; PERDIR — master switch
phpray.profile_mode       = sample   ; PERDIR — off | sample | url | all
phpray.profile_sample_rate= 3        ; PERDIR — % of requests function-profiled in "sample"
phpray.profile_url        = /cart    ; PERDIR — URI prefixes to profile in "url" mode
phpray.profile_functions  = 1        ; SYSTEM — register the observer at all (0 = zero cost)
phpray.output_mode        = shm      ; SYSTEM — file | shm | both

残りのディレクティブ（スマートサンプリングのしきい値、無視する URI、リングバッファーのサイズ、ヘッダーの出力など）については、docs/ に記載されています。

Apache（mod_php / LiteSpeed）でのサイトごとの制御、または適切なプールの .user.ini を使った制御：

# .htaccess — mod_php only
php_value phpray.profile_mode url
php_value phpray.profile_url /checkout

; .user.ini — PHP-FPM / LiteSpeed
phpray.profile_mode = sample
phpray.profile_sample_rate = 5

すべてのフック（MySQL/curl/ファイル、エラーコールバック、オブザーバー）は、phpray.enabled の値にかかわらず MINIT でインストールされます。そのため、サーバー全体で無効になっていても、単一のサイトだけを有効にできます。オブザーバーを完全に使わずに実行する唯一の方法は、phpray.profile_functions = 0 にすることです。JSONL レコードは O_APPEND ディスクリプター上で1回の write() によって書き込まれるため、同時に動作するワーカー間で行が混在することはありません。

オーバーヘッド

常時有効なトレース層は、ホットパスへの追加負荷を可能な限り小さくするよう設計されています。数値は、実際の WooCommerce テストストア（Storefront テーマ、有効なプラグイン22個、OPcache を使用した PHP 8.3）で、拡張機能の有効時と無効時を比較して測定したものであり、合成スクリプトで測定したものではありません。ワークロード、環境、各数値の測定方法、誤差の範囲を含む詳細な方法論は、docs/ に記載されています。

ステータス（2026年9月）： ラップトップでの内部テストでは、常時有効な層の値は素の PHP のベースラインと測定誤差の範囲内でした。一方、すべてのリクエストをプロファイリングした場合はベースラインを超えることが測定可能でしたが、従来の execute_ex フックよりは大幅に低い値でした。これらの数値は製品の数値としては公開していません。認定済みの数値、測定方法、未加工データは、専用の静かなホストでのベンチマーク後に公開します。

アーキテクチャ

 PHP process
   └─ phpray.so (hooks RINIT/RSHUTDOWN, mysqli/PDO, curl, files, errors, observer)
         │
         └─► ring buffer (/dev/shm)  and/or  JSONL file
                   │
                   ▼
        phpray-collector (single Go binary, systemd unit)
         ├─► SQLite (traces, queries, components, 1-min aggregates, retention)
         ├─► REST API  /api/v1/*  +  embedded dashboard
         └─► (optional) PHPRay Cloud ingest

プラグイン

それぞれ独自のリポジトリで管理しています。独自のリリースサイクルがあり、WordPress の場合は独自のライセンスもあるためです。

WordPress（GPLv2+）。PHP 拡張機能を読み込めない場合（ホスティング共有サーバー、PaaS など）、このプラグインは純粋な PHP 製のコレクターとして機能します。$wpdb、HTTP API、エラーハンドラーをフックし、同じトレース形式でローカルコレクターまたは PHPRay Cloud に送信します。拡張機能がなくても、常時稼働するレイヤー（タイミング、SQL、HTTP、エラー、N+1）を利用できます。また、確認できない4つの項目については README に明記されています。

DirectAdmin（Apache-2.0）。2種類のビューを備えたコントロールパネルプラグインです。顧客には自身のドメインが表示され、管理者にはサーバー全体が表示されます。CloudLinux では、拡張機能をアカウントごとに有効または無効にできます。.user.ini ではできない設定です。PHP がディレクトリごとの値を読み取るのは、モジュールの起動よりかなり後だからです。また、顧客は SSH を使わずに「この URL プレフィックスを N 分間プロファイリングする」こともできます。

PHPRay Cloud

Host Edition の顧客と、ホスト型コンソールを利用したい方は、トレースを PHPRay Cloud に送信できます。複数ドメインの一括表示、データ保持と履歴、アラート、クライアント向けのホワイトラベル診断レポートを利用できます。プラン：Free、Solo 月額 19、Studio 月額 99、Agency 月額 249、Fleet 月額 499 USD。Host Edition は年払いです。https://phpray.dev/pricing をご覧ください。PHP 拡張機能とローカルコレクターは引き続き無料のオープンソースです。クラウドは任意の送信先であり、依存先ではありません。

ソースからのビルド

# extension
cd src/extension
phpize && ./configure --enable-phpray && make -j$(nproc) && sudo make install

# collector
cd src/collector
go build -o phpray-collector .

コントリビュート

Developer Certificate of Origin（DCO）を採用しています。各コミットに git commit -s でサインオフしてください。大規模な変更を行う前に、Issue を作成してください。

セキュリティ

セキュリティ上の問題を報告するには、[email protected] までメールでご連絡ください（PGP はウェブサイトにあります）。公開 Issue は作成しないでください。

ライセンス

Apache License, Version 2.0 — LICENSE をご覧ください。

商標

「PHPRay」は IQhost の商標です。拡張機能、コレクター、およびこのリポジトリのライセンスは上記のとおりです。商標の使用権は付与されていません。

---

IQhost が開発しています。IQhost は、数千のサイトで PHP を運用するヨーロッパのホスティングプロバイダーです。PHPRay はそこで開発され、最初に導入されました。