Lambda ログ API - AWS Lambda

Lambda ログ API

Lambda は、ランタイムログを自動的にキャプチャし、Amazon CloudWatch にストリームします 。このログストリームには、 関数コードと拡張機能が生成するログと、Lambda が関数呼び出しの一部として生成するログが含まれます。

Lambda の拡張機能では、Lambda ランタイムログ API を使用して、Lambda 実行環境で直接ログストリームをサブスクライブできます。Lambda は、ログを拡張機能にストリームし、拡張機能は、ログを処理、フィルタリングして、指定された宛先に送信します。


      拡張機能 API と Logs API は、Lambda と外部拡張を接続します。

Logs API を使用すると、拡張機能は 3 つの異なるログストリームにサブスクライブできます。

  • Lambda 関数が生成して、stdout または stderr に書き込む関数ログ。

  • 拡張コードが生成する拡張ログ。

  • Lambda プラットフォームログ。呼び出しと拡張機能に関連するイベントとエラーを記録します。

注記

Lambda は拡張機能が 1 つまたは複数のログストリームにサブスクライブしている場合でも、すべてのログを CloudWatch に送信します。

サブスクライブしてログを受信する

Lambda 拡張機能は、Logs API にサブスクリプションリクエストを送信することで、ログを受信するようサブスクライブできます。

ログを受信するためにサブスクライブするには、内線識別子(Lambda-Extension-Identifier)が必要です。最初に 内線番号を登録 し、内線番号を受け取ります。そして 初期化中 に Logs API にサブスクライブします。初期化フェーズの完了後は、Lambda はサブスクリプションリクエストを処理しません。

注記

Logs API サブスクリプションは冪等です。サブスクリプションリクエストが重複しても、サブスクリプションが重複することはありません。

メモリ使用量

サブスクライバの数が増加すると、メモリ使用量は直線的に増加します。サブスクリプションは、各サブスクリプションが新しいメモリバッファを開き、ログを保存するため、メモリリソースを消費します。メモリ使用量を最適化するために、 バッファリング設定 を調整できます。バッファメモリ使用量は、実行環境の全体的なメモリ消費量の一部としてカウントされます。

送信先プロトコル

ログを受信するには、次のいずれかのプロトコルを選択できます。

  1. HTTP (推奨) - Lambda は JSON 形式の記録の配列として、ローカル HTTP エンドポイント (http://sandbox.localdomain:${PORT}/${PATH}) にログを配信します。$PATH パラメータはオプションです。HTTP のみがサポートされ、HTTPS はサポートされません。ログを受信するには、PUT または POST のいずれかを選択できます。

  2. TCP - Lambda は改行区切りの JSON (NDJSON) 形式で TCPポートにログを配信します。

TCP ではなく HTTP を使用することをお勧めします。TCP では、Lambda プラットフォームはログをアプリケーション層に配信するときに確認できません。したがって、拡張機能がクラッシュすると、ログが失われる可能性があります。HTTP はこの制限を共有しません。

また、サブスクライブしてログを受信する前に、ローカル HTTP リスナーまたは TCP ポートを設定することをお勧めします。セットアップ中に、次の点に注意してください。

  • Lambda は、実行環境内の送信先にのみログを送信します。

  • Lambda は、リスナーがない場合、または POST や PUT リクエストの結果でエラーが発生した場合は、ログ送信の試行を再試行します (バックオフあり)。ログサブスクライバーがクラッシュした場合、Lambda が実行環境を再起動した後もログを受信し続けます。

  • Lambda がポート 9001 を予約しています。他のポート番号の制限や推奨事項はありません。

バッファリング構成

Lambda はログをバッファリングし、サブスクライバに配信できます。サブスクリプションリクエストでこの動作を設定するには、次のオプションフィールドを指定します。Lambda では、指定しないフィールドにはデフォルト値が使用されます。

  • timeoutMs - バッチをバッファーする最大時間(ミリ秒単位)。デフォルト: 1,000。最小: 25 最大: 30,000。

  • maxBytes - メモリにバッファするログの最大サイズ (バイト単位)。デフォルト: 262,144。最小: 262,144。最大: 1,048,576。

  • MaxItems - メモリにバッファするイベントの最大数。デフォルト: 10,000。最小: 1,000。最大: 10,000。

バッファリングの設定時には、次の点に注意してください。

  • Lambda は、ランタイムがクラッシュした場合など、入力ストリームが閉じられている場合、ログをフラッシュします。

  • 各サブスクライバーは、サブスクリプションリクエストで異なるバッファリング設定を指定できます。

  • データを読み取るために必要なバッファサイズを考慮してください。サブスクライブリクエストで設定されている 2*maxBytes+metadata と同じ大きさのペイロード maxBytes を受信することを想定します。例えば、Lambda は次のメタデータバイトを各レコードに追加します。

    { "time": "2020-08-20T12:31:32.123Z", "type": "function", "record": "Hello World" }
  • サブスクライバが着信ログを十分な速さで処理できない場合、Lambda はログを削除して、メモリ使用率を制限し続ける可能性があります。削除されたレコードの数を示すために、Lambda は platform.logsDropped ログを送信します。

サブスクリプションの例

次の例は、プラットフォームログと関数ログをサブスクライブするリクエストを示しています。

PUT http://${AWS_LAMBDA_RUNTIME_API}/2020-08-15/logs HTTP/1.1 { "schemaVersion": "2020-08-15", "types": [ "platform", "function" ], "buffering": { "maxItems": 1000, "maxBytes": 262144, "timeoutMs": 100 }, "destination": { "protocol": "HTTP", "URI": "http://sandbox.localdomain:8080/lambda_logs" } }

リクエストが成功すると、サブスクライバーは HTTP 200 成功レスポンスを受信します。

HTTP/1.1 200 OK "OK"

ログ API のサンプルコード

カスタム送信先にログを送信する方法を示すサンプルコードについては、AWS Lambda コンピューティングブログの AWS 拡張機能を使用してログをカスタム送信先に送信するを参照してください。

基本的な Lambda 拡張機能を開発し、Logs API をサブスクライブする方法を示す Python および Go のコードサンプルについては、AWS Samples GitHub リポジトリの AWS LambdaExtensions を参照してください。Lambda 拡張機能の構築 に関する詳細については、Lambda 拡張機能 API を参照してください。

Logs API リファレンス

Logs API エンドポイントの値は、AWS_LAMBDA_RUNTIME_API の環境変数から取得できます。API リクエストを送信するには、API パスの前にプレフィックス 2020-08-15/ を使用します。以下に例を示します。

http://${AWS_LAMBDA_RUNTIME_API}/2020-08-15/logs

Log API の OpenAPI 仕様 (バージョン 2020-08-15) は、logs-api-request.zip から入手できます。

サブスクライブ

Lambda 実行環境で使用できる 1 つ以上のログストリームをサブスクライブするために、拡張機能が Subscribe API リクエストを送信します。

パス/logs

メソッドPUT

Body パラメータ

destination「」を参照してください。送信先プロトコル必須: はい。タイプ:文字列。

buffering「」を参照してください。バッファリング構成必須: いいえ。タイプ:文字列。

types - 受信するログのタイプの配列。必須: はい。タイプ: 文字列の配列 有効な値:「プラットフォーム」、「関数」、「拡張」。

schemaVersion - 必須: いいえ。デフォルト値: "2020-08-15". 拡張機能が platform.runtimeDone メッセージを受信するには、「2021-03-18」に設定します。

レスポンスパラメータ

サブスクリプションレスポンスの OpenAPI 仕様 (バージョン 2020-08-15) は、HTTP および TCP プロトコルで使用できます。

レスポンスコード

  • 200 - リクエストは正常に完了しました

  • 202 - リクエストは承認されました ローカルテスト中のサブスクリプションリクエストへのレスポンス。

  • 4XX - 無効なリクエスト

  • 500 - サービスエラー

リクエストが成功すると、サブスクライバーは HTTP 200 成功レスポンスを受信します。

HTTP/1.1 200 OK "OK"

リクエストが失敗した場合、サブスクライバはエラーレスポンスを受信します。以下に例を示します。

HTTP/1.1 400 OK { "errorType": "Logs.ValidationError", "errorMessage": URI port is not provided; types should not be empty" }

ログメッセージ

Logs API を使用すると、拡張機能は 3 つの異なるログストリームにサブスクライブできます。

  • 関数 - Lambda 関数が生成し、stdout または stderr に書き出すログ。

  • 拡張機能 - 拡張コードが生成するログ。

  • プラットフォーム - ランタイムプラットフォームが生成するログ。呼び出しと拡張機能に関連するイベントおよびエラーを記録します。

関数ログ

Lambda 関数と内部拡張機能は、関数ログを生成し、stdout または stderr に書き出します。

次の例は、関数ログメッセージの形式を示しています。 { "time": "2020-08-20T12:31:32.123Z", "type": "function", "record": "ERROR encountered. Stack trace:\n\my-function (line 10)\n" }

拡張ログ

拡張機能は、拡張ログを生成できます。ログ形式は、関数ログの場合と同じです。

プラットフォームログ

Lambda は、platform.startplatform.endplatform.fault などのプラットフォームイベントのログメッセージを生成します。

必要に応じて、platform.runtimeDone ログメッセージを含む Logs API スキーマの 2021-03-18 バージョンをサブスクライブできます。

プラットフォームログメッセージ例

次の例は、プラットフォームの開始ログと終了ログを示しています。これらのログは、requestId で指定された呼び出しの開始時刻と呼び出しの終了時刻を示します。

{ "time": "2020-08-20T12:31:32.123Z", "type": "platform.start", "record": {"requestId": "6f7f0961f83442118a7af6fe80b88d56"} } { "time": "2020-08-20T12:31:32.123Z", "type": "platform.end", "record": {"requestId": "6f7f0961f83442118a7af6fe80b88d56"} }

プラットフォームレポートログには、requestId で指定された呼び出しに関するメトリックが含まれます。呼び出しにコールドスタートが含まれている場合にのみ、initDurationMs フィールドがログに含まれます。AWS X-Ray トレースがアクティブである場合、ログには X-Ray メタデータが含まれます。次の例は、コールドスタートを含む呼び出しのプラットフォームレポートログを示しています。

{ "time": "2020-08-20T12:31:32.123Z", "type": "platform.report", "record": {"requestId": "6f7f0961f83442118a7af6fe80b88d56", "metrics": {"durationMs": 101.51, "billedDurationMs": 300, "memorySizeMB": 512, "maxMemoryUsedMB": 33, "initDurationMs": 116.67 } } }

プラットフォーム障害ログは、ランタイムまたは実行環境エラーをキャプチャします。次の例は、プラットフォーム障害ログメッセージを示しています。

{ "time": "2020-08-20T12:31:32.123Z", "type": "platform.fault", "record": "RequestId: d783b35e-a91d-4251-af17-035953428a2c Process exited before completing request" }

Lambda は、拡張機能が拡張 API に登録されると、プラットフォーム拡張ログを生成します。次の例は、プラットフォーム拡張メッセージを示しています。

{ "time": "2020-08-20T12:31:32.123Z", "type": "platform.extension", "record": {"name": "Foo.bar", "state": "Ready", "events": ["INVOKE", "SHUTDOWN"] } }

Lambda は、拡張機能がログ API をサブスクライブすると、プラットフォームログサブスクリプションログを生成します。次の例は、ログサブスクリプションメッセージを示しています。

{ "time": "2020-08-20T12:31:32.123Z", "type": "platform.logsSubscription", "record": {"name": "Foo.bar", "state": "Subscribed", "types": ["function", "platform"], } }

Lambda は、拡張機能が受信しているログの数を処理できない場合に、プラットフォームログをドロップしたログを生成します。次の例は、platform.logsDropped ログメッセージの例を示しています。

{ "time": "2020-08-20T12:31:32.123Z", "type": "platform.logsDropped", "record": {"reason": "Consumer seems to have fallen behind as it has not acknowledged receipt of logs.", "droppedRecords": 123, "droppedBytes" 12345 } }

プラットフォーム runtimeDone メッセージ

サブスクライブリクエストでスキーマバージョンを「2021-03-18」に設定した場合、Lambda は関数の呼び出しが正常に完了するか、エラーで終了した後に platform.runtimeDone メッセージを送信します。拡張機能は、このメッセージを使用して、この関数呼び出しのすべてのテレメトリ収集を停止できます。

スキーマバージョン 2021-03-18 での Log イベントタイプの OpenAPI 仕様は、schema-2021-03-18.zip から入手できます。

Lambda は、ランタイムが Next または Error ランタイム API リクエストを送信したときに platform.runtimeDone ログメッセージを生成します。platform.runtimeDone ログは、関数の呼び出しが完了したことを Logs API のコンシューマーに通知します。拡張機能は、この情報を使用して、呼び出し中に収集されたすべてのテレメトリをいつ送信するかを決定できます。

Lambda は、関数の呼び出しが完了したときに、ランタイムが NEXT リクエストを送信した後に platform.runtimeDone メッセージを送信します。次の例は、各ステータス値 (成功、失敗、タイムアウト) のメッセージを示しています。

例 成功した場合のメッセージ例

{ "time": "2021-02-04T20:00:05.123Z", "type": "platform.runtimeDone", "record": { "requestId":"6f7f0961f83442118a7af6fe80b88", "status": "success" } }

例 失敗した場合のメッセージ例

{ "time": "2021-02-04T20:00:05.123Z", "type": "platform.runtimeDone", "record": { "requestId":"6f7f0961f83442118a7af6fe80b88", "status": "failure" } }

例 タイムアウトした場合のメッセージ例

{ "time": "2021-02-04T20:00:05.123Z", "type": "platform.runtimeDone", "record": { "requestId":"6f7f0961f83442118a7af6fe80b88", "status": "timeout" } }