Lambda Logs API を使用する

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

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

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

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

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

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

メモリ使用量

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

送信先プロトコル

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

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

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

バッファリング構成

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

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

サブスクリプションの例

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

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 から入手できます。

Subscribe

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

パス – /logs

メソッド – PUT

Body パラメータ

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

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

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

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

リクエストが成功すると、サブスクライバーは 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 に書き出します。

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

拡張ログ

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

プラットフォームログ

Lambda は、platform.start、platform.end、platform.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"}   
}

platform.initRuntimeDone ログメッセージには、初期化ライフサイクルフェーズの一部である Runtime init サブフェーズのステータスが表示されます。Runtime init が正常に実行されると、ランタイムが /next Runtime API リクエスト (on-demand および provisioned-concurrency 初期化タイプの場合)、または restore/next (snap-start 初期化タイプの場合) を送信します。以下は、snap-start 初期化タイプに関する、正常に実行された Platform.InitRuntimedOne ログメッセージの例です。

{
  "time":"2022-07-17T18:41:57.083Z",
  "type":"platform.initRuntimeDone",
  "record":{
      "initializationType":"snap-start",
      "status":"success"
  }
}

platform.initReport ログメッセージには、Init フェーズの継続時間と、このフェーズ中に料金が請求されたミリ秒数が表示されます。初期化タイプが provisioned-concurrency の場合、Lambda は呼び出し中にこのメッセージを送信します。初期化タイプが snap-start の場合、Lambda はスナップショットの復元後にこのメッセージを送信します。以下は、snap-start 初期化タイプに関する platform.initReport ログメッセージの例です。

{
  "time":"2022-07-17T18:41:57.083Z",
  "type":"platform.initReport",
  "record":{
      "initializationType":"snap-start",
      "metrics":{
          "durationMs":731.79,
          "billedDurationMs":732
          }
  }
}

プラットフォームレポートログには、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"
}

"record":"RequestId: ...\tError: Runtime exited with error: exit status 255\nRuntime.ExitError"

"record":"RequestId: ... Status: error\tErrorType: Runtime.ExitError"

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
    }
}

platform.restoreStart ログメッセージには、Restore フェーズが開始された時刻が表示されます (snap-start 初期化タイプのみ)。例：

{ 
  "time":"2022-07-17T18:43:44.782Z", 
  "type":"platform.restoreStart", 
  "record":{} 
}

platform.restoreReport ログメッセージには、Restore フェーズの継続時間と、このフェーズ中に料金が請求されたミリ秒数が表示されます (snap-start 初期化タイプのみ)。例：

{
  "time":"2022-07-17T18:43:45.936Z",
  "type":"platform.restoreReport",
  "record":{
      "metrics":{
          "durationMs":70.87,
          "billedDurationMs":13
      }
  }
}

プラットフォーム 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"
  }
}

{
  "time":"2022-07-17T18:43:45.936Z",
  "type":"platform.restoreRuntimeDone",
  "record":{
      "status":"success"
  }
}