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 デベロッパーガイドの「コンソールを使用して Lambda 関数を作成する」で Lambda 関数を手動で呼び出して、結果、ログ、メトリクスを確認するセクションを参照してください。

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

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

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

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

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

• CloudFront コンソールを https://console.aws.amazon.com/cloudfront/v4/home で開きます。

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

コンソールでのテストでは関数のロジックのみを検証します。また、Lambda@Edge に固有のサービスクォータ (以前は制限と呼ばれていました) は適用されないことに注意してください。

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

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

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

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

CloudFront で Lambda@Edge 関数エラーが発生する原因

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

Lambda 関数実行エラー

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

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

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

CloudFront での実行は、Lambda サービスのクォータ (以前は制限と呼ばれていました) のために調整されます。

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

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

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

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

エラー率グラフ

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

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

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

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

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

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

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

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

Lambda が CloudFront に無効なレスポンスを返すと、Lambda 関数が実行されるリージョンで CloudFront が 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 Logs を検索します。詳細については、前のセクションの「Determining the Type of Failure」を参照してください。

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

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

注記

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

Lambda@Edge リージョンの判別

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

CloudFront コンソールの [Monitoring (モニタリング)] セクションでのグラフ表示の詳細については、「Amazon CloudWatch による 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 コンソールを開いてから [ロール] を選択して、アカウントのサービスにリンクされたロールのリストを表示します。次のロールを探してください。AWSServiceRoleForCloudFrontLogger