本番環境で PHP の例外をトレースする方法（再起動不要）

OpenResty XRay は、プロセスを再起動・変更することなく、本番環境で稼働中の PHP アプリケーションの例外をトレースします。プロセスをクラッシュさせる例外だけでなく、アプリケーション自身に捕捉されてクラッシュに至らない例外も検出対象です。PHP 言語レベルの例外フレームグラフを自動的に解釈し、例外を引き起こした正確なコードパスを特定しつつ、遅延に敏感な本番環境に適した最小限のパフォーマンスオーバーヘッドを実現します。

本チュートリアルでは、XRay の Guided Analysis 機能を使って実際の PHP アプリケーションで例外をトレースする手順を、分析の開始から自動生成レポートの確認まで解説します。

XRay の Guided Analysis で PHP の例外をトレースする

プロセスを確認して XRay コンソールを開く

まず、ps コマンドを実行して、PHP アプリケーションプロセスの完全なコマンドラインを確認します。

この php バイナリ実行ファイルが Linux ディストリビューションに付属していることがわかります。

OpenResty XRay を使用して、この未変更のプロセスを検査しましょう。内部で投げられる PHP 例外をリアルタイムで分析することができます。

OpenResty XRay の Web コンソールに移動します。

現在分析中のマシンが正しいことを確認します。

Guided Analysis で PHP の例外をスキャンする

「Guided Analysis」ページに入ります。

ここでは、システムが分析できる異なるタイプの問題を見ることができます。

「Errors & exceptions」を選択します。

「Next」をクリックします。

先ほどの PHP アプリケーションを選択します。

「Whole application」を選択します。

アプリケーションのタイプが正しいことを確認します。通常、デフォルト値で正しいです。

OpenResty XRay は、同時に複数の異なる言語レベルを分析できます。ここでは PHP と C/C++ の両方を選択したままにします。

最長の分析時間を設定することもできます。ここではデフォルトの 300 秒のままにします。

分析を開始します。

システムは複数のラウンドの分析を継続的に実行します。現在、最初のラウンドの分析を実行中です。

最初のラウンドの分析が完了し、2 回目のラウンドに入りました。この例では、1 回の分析で十分です。

分析を停止します。

例外レポートとホットコードパスを確認する

自動生成された分析レポートを見ることができます。

これは分析する問題のタイプです。「Errors & exceptions」です。

これは PHP コードパスを指しています。最も多くの例外を投げるコードパスが表示されています。

まず、配列の境界外アクセスエラーが見られます。

このエラーは業務コードの getOrder 関数内で発生しています。

Laravel のルーティングコンポーネントは、対応するビジネスロジックコードを実行するために、コントローラーメソッド callAction を自動的に呼び出します。

「More」をクリックして詳細を表示します。

このホットコードパスは、この PHP レベルの例外フレームグラフから自動的に導き出されたものです。

以下は問題のより詳細な説明と提案です。

ここで上記の例外について言及されています。

ここでは PHP エラーコードが発生した場所が指摘されています。

ここで提案された方法でこのエラーを回避できます。OpenResty XRay はこのエラーを修正するためのコード例も提供しています。

ホットコードパスから具体的な PHP のソース行を特定する

元のホットコードパスに戻りましょう。

getOrder 関数の緑色のボックスにマウスを合わせます。

ツールチップで PHP 関数のソースファイル名とフルパスを確認できます。

この PHP ソースコードの行番号は 54 です。

このアイコンをクリックして、この関数のソースファイルパスをコピーします。

ターミナルで vim エディタを使用してソースファイルを開きます。先ほどコピーしたファイルパスを貼り付けます。お好みのエディタを使用できます。

OpenResty XRay が提案したように 54 行目にジャンプします。

PHP 配列要素へのアクセスが見られます。orderId 変数の値が明らかに配列の境界を超えることがあります。ユーザーはこのソースコード行の前で、この配列インデックスの値をチェックする必要がありますが、まだチェックしていません。

この例外はアプリケーション自体によってキャッチされていますが、OpenResty XRay はそれでも検出することができます。

2 つ目の PHP 例外：throw 文による明示的な例外

次に、2 番目にプログラム例外を投げる PHP コードパスを見てみましょう。

これは PHP 業務コードが throw ステートメントを使って投げた例外です。

この例外も getOrder 関数によってトリガーされていることがわかります。

Guided Analysis 不要：PHP 例外の自動レポート

OpenResty XRay はオンラインプロセスを自動的に監視し、分析レポートを生成することもできます。

「Insights」ページに切り替えます。

「Insights」ページで、日次および週次の自動レポートを見つけることができます。そのため、「Guided Analysis」機能を使用する必要はありません。

もちろん、「Guided Analysis」はアプリケーションの開発とデモンストレーションに非常に有用です。

よくある質問

Q: OpenResty XRay はアプリケーションを再起動せずにどうやって PHP の例外を検出するのですか？ A: XRay は非侵襲的な動的トレーシングを使用します——内部では Y 言語が Stap+、eBPF+、GDB といった複数のランタイムをターゲットに駆動しており、稼働中の PHP プロセスを外部から観測することで、プロセス自体のコードやライフサイクルに触れることなく例外を捕捉します。

Q: アプリケーションがすでに処理してしまった PHP の例外も、XRay は検出できますか？ A: はい。例外がアプリケーション自身に捕捉されてクラッシュに至らない場合でも、XRay はその背後のコードパスを検出します。ログベースの手法の多くはこれを見逃します。

Q: 本チュートリアルの配列境界外例外はどのように発生していますか？ A: 業務コードの getOrder 関数が orderId 変数で PHP 配列にアクセスしていますが、この変数の値が配列の境界を超えることがあり、その前でインデックス値のチェックが行われていません——典型的な境界外アクセスのバグです。

Q: Guided Analysis を実行せずに PHP の例外レポートを確認するには？ A: XRay コンソールの「Insights」ページが日次・週次のレポートを自動生成するため、新しい例外を確認するたびに Guided Analysis を実行する必要はありません。

OpenResty XRay について

OpenResty XRay は動的トレーシング製品であり、実行中のアプリケーションを自動的に分析して、パフォーマンスの問題、動作の問題、セキュリティの脆弱性を解決し、実行可能な提案を提供いたします。基盤となる実装において、OpenResty XRay は弊社の Y 言語によって駆動され、Stap+、eBPF+、GDB、ODB など、様々な環境下で複数の異なるランタイムをサポートしております。

著者について

章亦春（Zhang Yichun）は、オープンソースの OpenResty^® プロジェクトの創始者であり、OpenResty Inc. の CEO および創業者です。

章亦春（GitHub ID: agentzh）は中国江蘇省生まれで、現在は米国ベイエリアに在住しております。彼は中国における初期のオープンソース技術と文化の提唱者およびリーダーの一人であり、Cloudflare、Yahoo!、Alibaba など、国際的に有名なハイテク企業に勤務した経験があります。「エッジコンピューティング」、「動的トレーシング」、「機械プログラミング」 の先駆者であり、22 年以上のプログラミング経験と 16 年以上のオープンソース経験を持っております。世界中で 4000 万以上のドメイン名を持つユーザーを抱えるオープンソースプロジェクトのリーダーとして、彼は OpenResty^® オープンソースプロジェクトをベースに、米国シリコンバレーの中心部にハイテク企業 OpenResty Inc. を設立いたしました。同社の主力製品である OpenResty XRay（動的トレーシング技術を利用した非侵襲的な障害分析および排除ツール）と OpenResty Edge（マイクロサービスおよび分散トラフィックに最適化された多機能ゲートウェイソフトウェア）は、世界中の多くの上場企業および大企業から高い評価を得ております。OpenResty 以外にも、章亦春は Linux カーネル、Nginx、LuaJIT、GDB、SystemTap、LLVM、Perl など、複数のオープンソースプロジェクトに累計 100 万行以上のコードを寄与し、60 以上のオープンソースソフトウェアライブラリを執筆しております。

翻訳

英語版の原文と日本語訳版（本文）をご用意しております。読者の皆様による他の言語への翻訳版も歓迎いたします。全文翻訳で省略がなければ、採用を検討させていただきます。心より感謝申し上げます！