OpenResty XRay を使用して HTTP 504 タイムアウトエラーを診断する方法

HTTP 504 ゲートウェイタイムアウトエラーとは、リバースプロキシとして動作している OpenResty または Nginx サーバーが、アップストリームサーバーからの応答を待ちきれずに諦めてしまった状態を指します。根本原因はほぼ必ず次の 3 つのいずれかです：アップストリームサーバーが遅い、両者間のネットワークリンクが遅い、あるいはプロキシ側のタイムアウト設定が短すぎる。本チュートリアルでは、OpenResty XRay を使用して、稼働中の OpenResty または Nginx サーバー上でこの 3 つのうちどれが原因かを特定する方法を解説します。

OpenResty アクセスログで 504 ゲートウェイタイムアウトを確認する

504 の調査はどのケースでもアクセスログから始まります。ここでは OpenResty のアクセスログを tail し、504 ステータスコードでフィルタリングしています。

ログから症状は十分に確認できます。/api/order/all と /api/sync/config のリクエストがすべて 504 を返しており、しかも数秒おきに繰り返し発生しています。これで 504 エラーが発生していることも、影響を受けているエンドポイントも判明しました。

しかしアクセスログから得られる情報はここまでです。アップストリームサーバーが遅い、ネットワークリンクが遅い、プロキシのタイムアウトが短すぎる——この 3 つはいずれもまったく同じ 504 ログを生成するため、ステータスコードだけでは区別できません。どれが本当の原因かを知るには、504 を引き起こした TCP 接続の内部を覗き込み、時間が実際にどこで消費されたかを突き止める必要があります。それを行うのが次のステップです。

OpenResty XRay の Guided Analysis で根本原因を特定する

OpenResty XRay は稼働中のサーバー上でこれらの 504 エラーを分析し、接続内部で実際に何が起きていたかを正確に再構成できます。XRay の Web コンソールを開き、監視対象のマシンが正しいことを確認したうえで、Guided Analysis ページを開き、診断したい問題の種類を選択します。

セットアップは短いです：Errors & exceptions を選択し、先ほどの OpenResty アプリケーションを選び、範囲を Whole Application にし、言語レベルは Lua と C/C++ のまま、分析時間もデフォルトの 300 秒のままで開始します。XRay は複数ラウンドの分析を自動で実行し、レポートを生成します。

レポートを読む：一度の分析で 2 種類の 504 を同時に検出

生成されたレポートは、すべての問題を Errors & Exceptions の下にまとめて表示します。このサーバーでは、一度の分析で 2 つの異なる HTTP 504 問題が浮かび上がりました。

この 2 つの一行サマリーをよく読んでください。まったく異なる 2 種類の失敗モードを表しています：

• 1 つ目の 504 は 3.19 秒かかりました。原因は、現在のサーバーが ACK を送った後に、133.91.43.213:80 のアップストリームサーバーが PSH+ACK パケットを遅延して送信したためです。
• 2 つ目の 504 は、アップストリームがパケットを一切返さなかったために発生しました。現在のサーバーは待ち続けた後、諦めて自ら接続を閉じました。

この 2 つを見分けるコツは非常にシンプルで、本記事全体で最も有用な考え方です：接続内で最も遅かったパケットに注目し、それが現在のサーバーが受信したものか送信したものかを問うことです。以下の 2 つのケースは、それぞれの結末を示します。

ケース 1：遅延はアップストリームが送ったパケットにある

1 つ目の 504 を展開すると、XRay は問題の TCP 接続上のすべてのパケットを順番にプロットし、それぞれのパケットが直前のパケットから何秒経過して届いたかを示します。

このグラフは一目で読み取れます。横軸はパケットの順序（1、2、3……）、縦軸は各パケットの直前パケットからの遅延、四角は現在のサーバーが送信したパケット（egress）、丸は現在のサーバーが受信したパケット（ingress） を表します。ほとんどすべての間隔はほぼゼロですが、ただ 1 つの丸——PSH+ACK パケット——だけが 3 秒を超えて跳ね上がっています。マウスを合わせると、具体的な数値と方向を確認できます。

この突出した点は丸、つまり現在のサーバーがアップストリームから受信するのを待っていたパケットです。言い換えると、現在のサーバーは自分の仕事を時間通りに終えたうえで、アップストリームからの応答を 3 秒間じっと待っていたということになります。XRay は結論と 3 つの候補となる根本原因（アップストリームサーバーが遅い、両者間のネットワークリンクが遅い、あるいはプロキシ側のタイムアウト設定が短すぎる）を提示してくれます。さらに重要なのは、それらを具体的な確認項目に落とし込んで示してくれる点です。

ケース 2：遅延は現在のサーバーが送ったパケットにある

2 つ目の 504 はレポート上の記述は似ていますが、パケットのグラフはちょうど鏡合わせになっています。

今回、最も遅いパケットは四角で、FIN+ACK フラグを持っています。四角は現在のサーバーが送信したことを意味し、FIN+ACK はそのパケットが接続を閉じたことを意味します。つまりストーリーはまったく異なります：アップストリームは 1 パケットも送ってこず、現在のサーバーが自身のタイムアウト保護に引っかかり、待つのをやめて自ら接続を切断したのです。

これが診断手法全体を一文にまとめたものです：同じ 504 ステータスコードでも、遅かったのが受信したパケットなら、まだアップストリームを待っている状態。遅かったのが送信した FIN+ACK なら、自身のタイムアウトが先に発火し、こちらから接続を閉じた状態。 どちらも最終的には同じ 3 つの根本原因に行き着きますが、どちら側が先に詰まったかを知れば、まずどこを見るべきかが分かります。

OpenResty XRay は、504 エラーが発生した TCP 接続のパケットのみをアプリケーションレベルでキャプチャするため、パフォーマンスへの影響は極めて小さく抑えられます。これはパフォーマンスとレイテンシーに厳しい要件がある本番環境に最適です。これが当社の強力なスマートパケットキャプチャ技術です。

完全自動化された分析とレポート

上記の Guided Analysis は、障害が起きている最中に使うツールです。日常的なモニタリングでは、Insights ページが同じ分析を自動的に実行し、日次・週次レポートとして公開してくれます。

同じ 2 つの 504 問題がここに自動で現れます——分析を明示的に起動する必要はありません。Guided Analysis は発生中の障害の調査や、個別のケースを詳しく解説する場面で引き続き有用です。一方 Insights は、こうした繰り返し発生する問題が日常運用のなかで見落とされないことを保証してくれます。

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 以上のオープンソースソフトウェアライブラリを執筆しております。

翻訳

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