504 Gateway Timeout

このエラーの意味と見分け方

• ブラウザーがすぐに失敗するのではなく、しばらく待った後に 504 Gateway Timeout を表示する。
• レポート、バルクインポート、エクスポート、画像処理、複雑な検索は失敗する一方、単純なページは引き続き表示できる。
• アプリケーションが混雑している場合や、リクエストがキューに入っている場合に失敗しやすくなる。
• バックエンドを直接テストすると応答するが、プロキシ、CDN、ロードバランサー経由では同じリクエストがタイムアウトする。
• ゲートウェイのログに、504が返されるまで上流へのリクエストが長時間継続していたことが記録されている。
• ブラウザーがタイムアウトを受け取った後もアプリケーションが処理を続けることがあり、操作を再試行すると重複処理や放棄された処理が発生する可能性がある。

可能性の高い順の主な原因

1. 遅い、またはブロックされたデータベースクエリ: インデックス不足、テーブルの肥大化、非効率なクエリ、ロック競合により、ゲートウェイの制限時間を超えてアプリケーションが待機することがあります。
2. バックエンドの過負荷またはキュー待ち: アプリケーションワーカー、データベース接続、CPU、メモリ、その他の限られたリソースが空くまで、リクエストが待機している可能性があります。
3. 実際に長時間かかる同期処理: 大規模なエクスポート、インポート、レポート、ファイル処理は正当な処理でも、通常のページリクエストには適さない場合があります。
4. 遅い下流APIまたはWebhook: 応答を返す前に、アプリケーションが別のサービスからの応答を待っている可能性があります。
5. 制限の厳しいプロキシまたはサーバーのタイムアウト: Nginx、Apache、CDN、ロードバランサーが、アプリケーションの処理完了前に待機を停止することがあります。
6. ゲートウェイレイヤー間のネットワーク問題: アプリケーションの処理時間だけでは遅延を説明できない場合、特に複数サーバーまたはマルチリージョン構成では、遅延、断続的なパケットロス、ルーティング障害の可能性が高まります。

修正方法

1. 失敗したリクエストと所要時間を特定する

504の原因となったリクエストについて、ゲートウェイとアプリケーションのアクセスログを確認します。ルートまたはユーザー操作、タイムスタンプ、応答時間、すべてのリクエストが失敗しているのか特定の操作だけが失敗しているのかを記録してください。

レポート、インポート、エクスポート、複雑な検索だけが失敗している場合は、インシデントをサーバー全体の停止として扱うのではなく、その操作から調査を始めます。

2. バックエンドと完全なリクエスト経路を比較する

認証を行い、安全なテストリクエストを使用して、バックエンドへ直接アクセスした場合の応答時間と、プロキシ、CDN、ロードバランサー経由で同じリクエストを送った場合の応答時間を比較します。

• 直接アクセスでもゲートウェイ経由でも遅い場合は、アプリケーション、データベース、容量、または依存サービスが原因である可能性があります。
• 直接アクセスでは速いのにプロキシ経由では失敗する場合は、仲介レイヤーのタイムアウト、ルーティングの問題、またはゲートウェイとバックエンド間のネットワーク問題が考えられます。

本番環境のアクセス制御を回避したり、テストだけを目的に状態を変更するリクエストを送信したりしないでください。

3. データベースの処理時間とロック待ちを調査する

使用しているデータベースプラットフォームの運用ガイダンスに従い、データベースのスロークエリおよびロック待ちに関する診断機能を有効化するか、診断結果を確認します。現在有効なゲートウェイのタイムアウト付近、またはそれを超えて実行されているクエリを探してください。

インデックス不足、非効率な結合やフィルター、テーブルの増大、ロック競合を確認します。測定されたボトルネックに効果があることを確認してから、クエリを最適化し、処理対象のデータを減らすか、インデックスを追加してください。スキーマやインデックスの変更はリソースを消費し、同時実行中のワークロードに影響する可能性があるため、データベース担当者と調整してください。

すぐに完了すべきクエリを隠すためだけに、タイムアウトを延長しないでください。

4. バックエンドの容量とキューを確認する

障害発生時のアプリケーション、Webサーバー、システムのメトリクスを確認し、ワーカー枯渇、リクエストのキュー待ち、データベース接続数の上限、CPUまたはメモリの逼迫、その他のリソース制約を調べます。

リクエストが容量待ちになっている場合は、タイムアウトを延長する前にそのボトルネックに対処してください。容量やプロセスの設定変更はサービスの安定性に影響する可能性があるため、適用される運用上の承認と変更プロセスに従って実施してください。

5. 長時間の処理をバックグラウンドジョブへ移行する

インポート、エクスポート、レポート生成、メール処理などのタスクでは、アプリケーションが対応している場合、バックグラウンドジョブを使用します。最初のリクエストでは処理を開始またはキューに追加し、別のステータス画面または通知で進行状況と完了を知らせるようにします。

これにより、処理全体が終わるまでブラウザー接続、ゲートウェイワーカー、アプリケーションリクエストを保持し続ける必要がなくなります。この方式を有効にする前に、ジョブに適切な再試行処理と重複送信への対策があることを確認してください。

6. Nginxのタイムアウト設定を慎重に確認する

Nginxがゲートウェイの場合、該当する server または location ブロックの proxy_read_timeout と proxy_connect_timeout 設定を確認します。変更する前に、どのレイヤーがタイムアウトを適用しているのかを確認してください。

処理に時間がかかることが想定され、バックエンドが正常で、接続数やワーカー使用量の増加を許容できる場合に限り、タイムアウトを延長します。設定変更には適切な承認が必要です。変更を保存した後、設定を検証して通常のデプロイ手順に従ってNginxをリロードし、以前失敗した操作を再実行します。計画外の変更で、サービスのリロードと読み取り専用の診断を同時に行わないでください。

7. Apacheのプロキシ設定を確認する

mod_proxy を使用するApacheでは、該当する Timeout と ProxyTimeout の設定を確認します。大容量のアップロードが関係する場合は、関連する mod_reqtimeout の動作も確認してください。

可能な場合は、承認とロールバック計画を用意したうえで、影響を受けるルートまたは操作に対して最も限定的で安全な変更を適用します。同じリクエストで再テストし、待ち時間が長くなったことでワーカーや接続が枯渇していないことを確認してください。

8. CDNとロードバランサーの動作を確認する

サイトでCloudflareなどのCDNまたはロードバランサーを使用している場合、そのサービスのゲートウェイタイムアウト、オリジンへのルーティング、健全性、プランレベルの設定を確認します。利用可能な設定では延長できない制限を、仲介レイヤーが適用している可能性があります。

オリジンの処理にその制限を超える時間が必要な場合は、ブラウザーリクエストを長く保持するのではなく、処理を最適化するか、非同期処理へ移行してください。

9. 遅いサードパーティ呼び出しを切り分ける

外部APIまたはWebhookの呼び出しをそれぞれ個別に測定します。対応している場合は依存サービスに短めの内部タイムアウトを設定し、失敗を明示的に処理して、後から完了できる場合は保留中または再試行可能な状態を返します。

信頼性の低い依存サービスによってゲートウェイのタイムアウト全体が消費されないようにしてください。自動再試行を追加する前に、再試行回数に上限があり、安全に実行できることを確認します。

10. 修正を検証する

以前失敗したページ操作またはリクエストを正確に再実行します。現在有効なゲートウェイのタイムアウト以内に完了することを確認し、その後ログを調べて、バックエンドに放棄された処理、重複処理、異常に長時間実行される処理が蓄積していないことを確認します。バックエンドへの直接アクセスだけでなく、本番環境の完全な経路を通してテストしてください。

予防と修正確認

• インポート、エクスポート、レポート生成、メール処理など、通常のページリクエストを超える可能性がある処理にはバックグラウンドジョブを使用する。
• データ量の増加に伴い、頻繁にタイムアウトするページの背後にあるデータベース処理について、インデックスとクエリプランを確認する。
• リクエスト時間、キュー待ち時間、データベース処理時間、ワーカー使用量、依存サービスの処理時間を個別に監視する。
• 最も時間のかかる正当な処理を基準にプロキシとアプリケーションのタイムアウトを意図的に設定し、サードパーティ依存サービスのタイムアウトには上限を設ける。
• 重要な処理はオリジンだけでなく、CDNまたはロードバランサーを含む本番環境の完全な経路を通してテストする。
• ゲートウェイのタイムアウトによってジョブやトランザクションが重複しないよう、再試行と再送信を安全に設計する。
• 変更後はタイムアウトした操作を正確に再実行し、過剰なキュー待ち処理を蓄積せずに完了することを確認する。

よくある質問