Amazon CloudFront
開発者ガイド (API バージョン 2016-09-29)

Lambda@Edge 関数のテストとデバッグ

このトピックでは、Lambda@Edge 関数をテストおよびデバッグするための戦略を説明するセクションを示します。Lambda@Edge 関数コードのスタンドアロンをテストすること、目的のタスクの完了を確認すること、統合のテストを行うこと、CloudFront で関数が正しく機能しているか確認することは重要です。

統合テスト中または関数がデプロイされた後に、HTTP 5xx エラーなどの CloudFront エラーのデバッグが必要になることがあります。エラーは、Lambda 関数から返される無効なレスポンス、関数がトリガーされるときの実行時のエラー、または Lambda サービスによる実行スロットリングが原因のエラーの可能性があります。このトピックのセクションでは、どのタイプの障害が問題であるかを判別するための戦略、そしてその問題を解決するためのステップを共有します。

注記

エラーをトラブルシューティングするときに CloudWatch ログファイルまたはメトリクスを確認する場合は、関数が実行される場所に最も近いリージョンに表示または保存されていることに注意してください。したがって、たとえば英国のユーザーがいるウェブサイトまたはウェブアプリケーションで、ディストリビューションに関連する Lambda 関数がある場合は、リージョンを変更してロンドン AWS リージョンの CloudWatch メトリクスまたはログファイルを表示する必要があります。詳細については、このトピックの後半の「Lambda@Edge リージョンの判別」を参照してください。

Lambda@Edge 関数のテスト

Lambda 関数をテストするには、スタンドアロンテストと統合テストの 2 つのステップがあります。

スタンドアロン機能のテスト

CloudFront に Lambda 関数を追加する前に、Lambda コンソールでテスト機能を使用するか他の方法を使用して、必ず最初に機能をテストしてください。Lambda コンソールのテストの詳細については、AWS Lambda Developer Guideの「コンソールを使用して Lambda 関数を作成する」の「Lambda 関数を手動で呼び出し、結果、ログ、メトリクスを確認する」セクションを参照してください。

CloudFront での関数のオペレーションのテスト

統合テストを完了することが重要です。ここで、関数はディストリビューションに関連付けられ、CloudFront イベントに基づいて実行されます。関数が正しいイベントに対してトリガーされることを確認し、CloudFront に対して有効で正しいレスポンスを返します。たとえば、イベント構造が正しいこと、有効なヘッダーだけが含まれていることなどを確認します。

Lambda コンソールの関数で統合テストを繰り返す場合、コードを変更する際や関数を呼び出す CloudFront トリガーを変更する際は、Lambda@Edge チュートリアルのステップを参照しください。たとえば、チュートリアルの「 ステップ 4: 関数を実行する CloudFront トリガーを追加する」のステップで説明しているように、関数の番号付きバージョンを操作していることを確認します。

変更を加えた場合やデプロイした場合、更新した関数と CloudFront トリガーがすべてのリージョンにレプリケートするまで数分かかることに注意してください。通常、これには数分かかりますが、最大で 15 分かかる場合があります。

レプリケーションが終了したかどうかを確認するには、CloudFront コンソールに移動し、ディストリビューションを表示します。

  • CloudFront コンソール (https://console.aws.amazon.com/cloudfront/) に移動します。

ディストリビューションのステータスが [進行中] から [デプロイ済み] に戻ったことを確認します。この場合、関数はレプリケートされたことを意味します。続いて、次のセクションのステップに従って関数が機能することを確認します。

コンソールでのテストではロジックのみを検証し、Lambda@Edge に固有のサービス制限は適用されないことに注意してください。

CloudFront での Lambda 関数エラーの識別

関数のロジックが正しく機能することを確認した後、CloudFront での関数の実行時に HTTP 5xx エラーが継続することがあります。HTTP 5xx エラーはさまざまな理由で返される可能性があります。これには、Lambda 関数エラーやその他の CloudFront の問題が含まれる場合があります。

  • Lambda@Edge 関数を使用している場合は、CloudFront コンソールのグラフを使用してエラーの原因を突き止め、それを修正することができます。たとえば、HTTP 5xx エラーの原因が CloudFront によるものか、Lambda 関数によるものかを確認し、特定の関数については関連するログファイルを表示して問題を調査できます。

  • HTTP エラー全般を CloudFront でトラブルシューティングするには、オリジンからのエラーレスポンスのトラブルシューティング のトピックのトラブルシューティング手順を参照してください。

CloudFront での Lambda 関数エラーの原因

Lambda 関数が HTTP 5xx エラーの原因となる可能性がある理由はいくつかあります。実行するトラブルシューティングステップはエラーのタイプによって異なります。エラーは次のように分類されます。

Lambda 関数実行エラー

関数に処理されない例外があるため、またはコードにエラーがあるため、CloudFront が Lambda からレスポンスを得られないときに実行エラーが発生します。たとえば、コードにコールバック (エラー) が含まれている場合です。詳細については、AWS Lambda Developer Guide の「Lambda 関数エラー」を参照してください。

無効な Lambda 関数のレスポンスが CloudFront に返される。

関数の実行後、CloudFront が Lambda からレスポンスを受け取ります。レスポンスのオブジェクト構造が Lambda@Edge イベント構造 に従わない場合、またはレスポンスに無効なヘッダーや他の無効なフィールドが含まれている場合、エラーが返されます。

Lambda サービスの制限のため、CloudFront での実行が制限されます。

Lambda サービスは各リージョンでの実行を制限し、上限に達するとエラーが返されます。

障害のタイプを判断する方法

デバッグするときにどこに焦点を合わせて CloudFront から返されたエラーを解決するかを決めるのに役立つように、なぜ CloudFront が HTTP エラーを返しているのかを識別することは役立ちます。開始するには、AWS マネジメントコンソール の CloudFront コンソールの [Monitoring] セクションにあるグラフを使うことができます。詳細については、 CloudFront コンソールの [Monitoring] セクションでのグラフの表示の詳細については、「CloudFront のモニタリング とアラームの設定」を参照してください。

次のグラフは、エラーが発生源によって返されたのか Lambda 関数によって返されたのかを追跡し、Lambda 関数からのエラーである場合に問題の種類を絞り込む場合に特に役立ちます。

エラー率グラフ

各ディストリビューションの [Overview] タブに表示できるグラフの1つが、[Error rates] グラフです。このグラフは、ディストリビューションに対するすべてのリクエストに対するエラーの割合をパーセンテージで表示します。グラフは、Lambda 関数の合計エラー率、合計 4xx エラー、合計 5xx エラー、合計 5xx エラーを示しています。エラーの種類と量に基づいて、原因を調査してトラブルシューティングするための手順を実行できます。


								CloudFront ディストリビューションのエラー率グラフ
  • Lambda エラーが表示された場合は、関数が返す特定の種類のエラーを調べることで、さらに詳しく調べることができます。[Lambda@Edge errors] タブには、特定の関数に関する問題を特定するのに役立つように、関数エラーをタイプ別に分類したグラフが含まれています。

  • CloudFront エラーが表示された場合は、トラブルシューティングを行い、オリジンエラーを修正したり、CloudFront 構成を変更したりすることができます。詳細については、「オリジンからのエラーレスポンスのトラブルシューティング」を参照してください。

Execution エラーと無効な関数レスポンスグラフ

[Lambda@Edge errors] タブには、特定のディストリビューションに対する Lambda@Edge エラーをタイプ別に分類したグラフが含まれています。たとえば、1 つのグラフに AWS リージョン別の実行エラーがすべて表示されます。問題のトラブルシューティングを容易にするために、同じページで、地域別に特定の関数のログファイルを開いて調べることで、特定の問題を探すことができます。[View execution error logs] または [View invalid function response] で、リージョン (実行エラーの場合は関数) を選択し、[View logs]を選択します。


								Lambda@Edge 関数実行のエラー率グラフ

								Lambda@Edge 関数実行のエラー率グラフ

さらに、トラブルシューティングとエラーの修正に関する推奨事項については、この章の次のセクションを参照してください。

スロットルグラフ

[Lambda@Edge errors] タブには、[Throttles] グラフも含まれます。場合によっては、リージョンの同時実行性の制限に達すると、Lambda サービスがリージョンごとに関数呼び出しを調整します。制限の超過エラーが表示される場合は、Lambda サービスがリージョンの実行に課す上限に関数が達しています。上限の増加をリクエストする方法など、詳細については、「Lambda@Edge の制限」を参照してください。


								Lambda@Edge 関数実行のスロットルグラフ

HTTP エラーのトラブルシューティングでこの情報を使用する方法の例については、「AWS でコンテンツ配信をデバッグするための 4 つの手順」を参照してください。

無効な Lambda 関数レスポンス (検証エラー) のトラブルシューティング

問題が Lambda 検証エラーであると特定した場合は、Lambda 関数が CloudFront に無効なレスポンスを返していることを意味します。このセクションのガイダンスに従い、関数を確認し、レスポンスが CloudFront 要件に従っていることを確認する手順を実行します。

CloudFront は、次の 2 つの方法で Lambda 関数からのレスポンスを検証します。

  • Lambda レスポンスは、必要なオブジェクト構造に従う必要があります。 不正なオブジェクト構造の例には次のようなものがあります。解析できない json、必須フィールドの欠落、レスポンスの無効なオブジェクト。詳細については、「Lambda@Edge イベント構造」を参照してください。

  • レスポンスには有効なオブジェクト値のみを含める必要があります。 レスポンスに有効なオブジェクトが含まれるがサポートされていない値がある場合、エラーが発生します。例には次のようなものがあります。ブラックリストに載せられているヘッダーまたは読み取り専用のヘッダーの追加または更新 (「Lambda 関数の要件と制限」トピックの ヘッダー を参照)、本文サイズの上限の超過 (「Lambda Response エラー」トピックの「生成されるレスポンスのサイズ制限を超えている」を参照)、無効な文字または値 (Lambda@Edge イベント構造 を参照)。

Lambda が CloudFront に無効なレスポンスを返すと、CloudFront が Lambda 関数が実行されるリージョンで CloudWatch にプッシュするログファイルにエラーメッセージが書き込まれます。これは、無効なレスポンスがあるときにログファイルを CloudWatch に送信するデフォルトの動作です。ただし、機能をリリースする前に Lambda 関数を CloudFront と関連付けると、関数に対して有効にならない可能性があります。詳細については、このトピックの後半の「アカウントがログを CloudWatch にプッシュするかどうかを判断する」を参照してください。

CloudFront は、関数が実行される場所に対応するリージョンの、ディストリビューションに関連するロググループにログファイルをプッシュします。ロググループの形式は以下のとおりです。/aws/cloudfront/LambdaEdge/DistributionId、ここで DistributionId はディストリビューションの ID です。CloudWatch ログファイルがあるリージョンを決定するには、このトピックの後半の「Lambda@Edge のリージョンの判別」を参照してください。

再現可能なエラーの場合、エラーになる新しいリクエストを作成し、障害のある CloudFront レスポンス (X-Amz-Cf-Id ヘッダー) でリクエスト ID を見つけて、ログファイル内の 1 つの障害を特定します。ログファイルのエントリには、エラーが返される理由を特定するのに役立つ情報が含まれます。また、対応する Lambda リクエスト ID もリスト表示されるため、1 つのリクエストのコンテキストでの根本原因を分析することもできます。

エラーが断続的な場合は、CloudFront アクセスログを使用して障害が発生したリクエストのリクエスト ID を見つけ、対応するエラーメッセージの CloudWatch ログを検索します。詳細については、前のセクションの「Determining the Type of Failure」を参照してください。

Lambda 関数実行エラーのトラブルシューティング

Lambda 実行エラーが問題である場合は、Lambda 関数のログ記録ステートメントを作成しておくと、CloudFront での関数の実行をモニタリングする CloudWatch ログファイルにメッセージを書き込み、正常に機能しているかどうかを判断するのに役立ちます。その後、これらのステートメントを CloudWatch ログファイルで検索して、関数が正常に機能していることを確認できます。

注記

Lambda@Edge 関数を変更していない場合でも、Lambda 関数の実行環境を更新すると、この関数に影響を与え、実行エラーが発生する可能性があります。テストおよび新しいバージョンへの移行の詳細については、「Upcoming updates to the AWS Lambda and AWS Lambda@Edge execution environment」を参照してください。

Lambda@Edge リージョンの判別

Lambda@Edge 関数がトラフィックを受信しているリージョンを確認するには、AWS マネジメントコンソール の CloudFront コンソールでその関数のメトリックを表示します。メトリックスは AWS リージョンごとに表示されます。同じページで、リージョンを選択してそのリージョンのログファイルを表示し、問題を調査することができます。CloudFront が Lambda 関数を実行したときに作成されたログファイルを表示するには、正しいリージョンで CloudWatch ログファイルを確認する必要があります。

CloudFront コンソールの [Monitoring] セクションでのグラフの表示の詳細については、「CloudFront のモニタリング とアラームの設定」を参照して ください。

アカウントがログを CloudWatch にプッシュするかどうかを判断する

デフォルトでは、CloudFront によって無効な Lambda 関数レスポンスのログ記録が有効になり、Lambda@Edge のサービスにリンクされたロール のいずれかを使用してログファイルを CloudWatch にプッシュします。無効な Lambda 関数レスポンスのログ機能がリリースされた前に CloudFront に追加した Lambda@Edge 関数がある場合は、CloudFront トリガーを追加するなど、Lambda@Edge 設定を次に更新するときにログ記録が有効になります。

次を実行して、アカウントでログファイルを CloudWatch にプッシュすることが有効になっているか確認できます。

  • ログが CloudWatch に表示されているか確認する。 必ず、Lambda@Edge 関数が実行されたリージョンを確認します。詳細については、「 Lambda@Edge リージョンの判別」を参照してください。

  • 関連するサービスにリンクされたロールが IAM のアカウントに存在するかどうかを確認する。 これを行うには、https://console.aws.amazon.com/iam/ で IAM コンソールを開いてから [Roles] を選択して、アカウントのサービスにリンクされたロールのリストを表示します。次のロールを探してください。AWSServiceRoleForCloudFrontLogger