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 エラーが継続することがあります。

CloudFront を使用している場合、さまざまな理由で HTTP 5xx エラーが返されることがあります。次のトピックでは、HTTP 5xx エラーを回避するのに役立つ、いくつかの一般的なトラブルシューティングステップについて説明します。オリジンからのエラーレスポンスのトラブルシューティング

CloudFront の構成に Lambda@Edge 関数が含まれている場合は、Lambda@Edge でエラーを追跡するために実行できる特定のステップがあります。Lambda 関数が HTTP 5xx エラーの原因となる可能性がある理由はいくつかあります。実行するトラブルシューティングステップはエラーのタイプによって異なります。エラーには以下が含まれます。

Lambda 関数実行エラー。

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

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

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

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

Lambda サービスは各リージョンでの実行を制限し、上限に達するとエラーが返されます。上限の増加をリクエストする方法など、詳細については、「Lambda@Edge の制限」を参照してください。

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

CloudFront がエラーを返している理由を特定することは、問題をデバッグおよび解決する際に焦点を当てる場所を判断するのに役立ちます。CloudFront レスポンスヘッダーとアクセスログには、問題を絞り込むのに役立つ情報が含まれます。

CloudFront レスポンスヘッダー

CloudFront X-Cache レスポンスヘッダーを確認して、障害のタイプを学ぶことができます。障害のタイプに応じて、X-Cache ヘッダーには以下が表示されます。

  • X-Cache: LambdaValidationError from CloudFront

  • X-Cache: LambdaExecutionError from CloudFront

  • X-Cache: LambdaLimitExceeded from CloudFront

CloudFront アクセスログ

または、CloudFront アクセスログでエラーを探すことができます。x-edge-result-type フィールドには以下が表示されます。

  • LambdaValidationError

  • LambdaExecutionError

  • LambdaLimitExceeded

注記

CloudFront アクセスログが更新されるまでわずかな遅延が生じることに注意してください。CloudFront は通常、ログに表示されるイベントの 1 時間以内にログに指定した Amazon S3 バケットにログファイルを配信します。ただし、ログファイルエントリの投稿に最大 24 時間の遅延が生じる場合があります。詳細については、「ログファイル配信のタイミング」を参照してください。

制限の超過エラーが表示される場合は、Lambda サービスがリージョンの実行に課す上限に関数が達しています。上限の増加をリクエストする方法など、詳細については、「Lambda@Edge の制限」を参照してください。

検証エラーまたは実行エラーが表示される場合は、推奨事項について次のセクションを参照してください。

無効な 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 リージョンの判別

CloudFront が Lambda 関数を実行したときに作成されたログファイルを表示するには、正しいリージョンで CloudWatch ログファイルを確認する必要があります。次の AWS CLI スクリプトを実行して、Lambda@Edge 関数がトラフィックを受信している可能性があるリージョンのリストを特定できます。これらのリージョンは、CloudWatch ログファイルを検索してエラーを除去するのに役立ちます。スクリプトを実行する前に、AWS CLI をインストールして使用するための手順を AWS Command Line Interface で確認してください。

FUNCTION_NAME=function_name_without_qualifiers for region in $(aws --output text ec2 describe-regions | cut -f 3) do for loggroup in $(aws --output text logs describe-log-groups --log-group-name "/aws/lambda/us-east-1.$FUNCTION_NAME" --region $region --query 'logGroups[].logGroupName') do echo $region $loggroup done done

このスクリプトからのレスポンスには、レプリケートされた Lambda@Edge 関数があるリージョン、少なくとも 1 回実行されたリージョンが示されます。

アカウントがログを 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