# Lambda Logs API を使用する
**重要**
Lambda Telemetry API は、Lambda Log API に取って代わる API です。**Logs API は引き続き完全に機能しますが、今後は Telemetry API のみを使用することをお勧めします。**拡張機能は、Telemetry API または Logs API のいずれかを使用して、テレメトリストリームにサブスクライブできます。これらの API のいずれかを使用してサブスクライブした後で、もう一方の API を使用してサブスクライブしようとすると、エラーが返されます。
**Lambda マネージドインスタンスは Logs API をサポートしていない**
Lambda マネージドインスタンスは Logs API をサポートしていません。マネージドインスタンス関数を使用している場合は、代わりに [Telemetry API](telemetry-api.md) を使用します。Telemetry API は、Lambda 関数からテレメトリデータを収集および処理するための拡張機能を提供します。
Lambda は、ランタイムログを自動的にキャプチャし、Amazon CloudWatch にストリームします 。このログストリームには、 関数コードと拡張機能が生成するログと、Lambda が関数呼び出しの一部として生成するログが含まれます。
[Lambda の拡張機能](runtimes-extensions-api.md)では、Lambda ランタイムログ API を使用して、Lambda [実行環境](lambda-runtime-environment.md)で直接ログストリームをサブスクライブできます。Lambda は、ログを拡張機能にストリームし、拡張機能は、ログを処理、フィルタリングして、指定された宛先に送信します。
![\[\]](http://docs.aws.amazon.com/ja_jp/lambda/latest/dg/images/logs-api-concept-diagram.png)
Logs API を使用すると、拡張機能は 3 つの異なるログストリームにサブスクライブできます。
+ Lambda 関数が生成して、`stdout` または `stderr` に書き込む関数ログ。
+ 拡張コードが生成する拡張ログ。
+ Lambda プラットフォームログ。呼び出しと拡張機能に関連するイベントとエラーを記録します。
**注記**
Lambda は拡張機能が 1 つまたは複数のログストリームにサブスクライブしている場合でも、すべてのログを CloudWatch に送信します。
**Topics**
+ [サブスクライブしてログを受信する](#runtimes-logs-api-subscribing)
+ [メモリ使用量](#runtimes-logs-api-memory)
+ [送信先プロトコル](#runtimes-logs-api-dest)
+ [バッファリング構成](#runtimes-logs-api-buffering)
+ [サブスクリプションの例](#runtimes-logs-api-subs-example)
+ [ログ API のサンプルコード](#runtimes-logs-api-samples)
+ [Logs API リファレンス](#runtimes-logs-api-ref)
+ [ログメッセージ](#runtimes-logs-api-msg)
## サブスクライブしてログを受信する
Lambda 拡張機能は、Logs API にサブスクリプションリクエストを送信することで、ログを受信するようサブスクライブできます。
ログを受信するためにサブスクライブするには、内線識別子（`Lambda-Extension-Identifier`）が必要です。最初に [ 内線番号を登録 ](runtimes-extensions-api.md#extensions-registration-api-a) し、内線番号を受け取ります。そして [ 初期化中 ](lambda-runtime-environment.md#runtimes-lifecycle-ib) に Logs API にサブスクライブします。初期化フェーズの完了後は、Lambda はサブスクリプションリクエストを処理しません。
**注記**
Logs API サブスクリプションは冪等です。サブスクリプションリクエストが重複しても、サブスクリプションが重複することはありません。
## メモリ使用量
サブスクライバの数が増加すると、メモリ使用量は直線的に増加します。サブスクリプションは、各サブスクリプションが新しいメモリバッファを開き、ログを保存するため、メモリリソースを消費します。メモリ使用量を最適化するために、[ バッファリング設定 ](#runtimes-logs-api-buffering) を調整できます。バッファメモリ使用量は、実行環境の全体的なメモリ消費量の一部としてカウントされます。
## 送信先プロトコル
ログを受信するには、次のいずれかのプロトコルを選択できます。
1. **HTTP** (推奨) - Lambda は JSON 形式の記録の配列として、ローカル HTTP エンドポイント (`http://sandbox.localdomain:${PORT}/${PATH}`) にログを配信します。`$PATH` パラメータはオプションです。HTTP のみがサポートされ、HTTPS はサポートされません。ログを受信するには、PUT または POST のいずれかを選択できます。
1. **TCP** - Lambda は[改行区切りの JSON (NDJSON) 形式](https://github.com/ndjson/ndjson-spec)で 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` ログを送信します。詳細については、「[Lambda: 関数のログの一部が表示されない](troubleshooting-execution.md#troubleshooting-execution-missinglogs)」を参照してください。
## サブスクリプションの例
次の例は、プラットフォームログと関数ログをサブスクライブするリクエストを示しています。
```
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 拡張機能を使用してログをカスタム送信先に送信する](https://aws.amazon.com/blogs/compute/using-aws-lambda-extensions-to-send-logs-to-custom-destinations/)を参照してください。
基本的な Lambda 拡張機能を開発し、Logs API をサブスクライブする方法を示す Python および Go のコードサンプルについては、AWS Samples GitHub リポジトリの [AWS LambdaExtensions](https://github.com/aws-samples/aws-lambda-extensions) を参照してください。Lambda 拡張機能の構築 に関する詳細については、[Lambda 拡張機能 API を使用した拡張機能の作成](runtimes-extensions-api.md) を参照してください。
## 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](samples/logs-api-request.zip) から入手できます。
### Subscribe
Lambda 実行環境で使用できる 1 つ以上のログストリームをサブスクライブするために、拡張機能が Subscribe API リクエストを送信します。
**パス** – `/logs`
**メソッド** – **PUT**
**Body パラメータ**
`destination`「」を参照してください。[送信先プロトコル](#runtimes-logs-api-dest)必須: はい。タイプ:文字列。
`buffering`「」を参照してください。[バッファリング構成](#runtimes-logs-api-buffering)必須: いいえ。タイプ:文字列。
`types` - 受信するログのタイプの配列。必須: はい。タイプ: 文字列の配列 有効な値：「プラットフォーム」、「関数」、「拡張」。
`schemaVersion` - 必須: いいえ。デフォルト値: "2020-08-15"。拡張機能が [`platform.runtimeDone`](#runtimes-logs-api-ref-done) メッセージを受信するには、「2021-03-18」に設定します。
****レスポンスパラメータ****
サブスクリプションレスポンスの OpenAPI 仕様 (バージョン **2020-08-15**) は、HTTP および TCP プロトコルで使用できます。
+ HTTP: [ logs-api-http-response.zip ](samples/logs-api-http-response.zip)
+ TCP: [ logs-api-tcp-response.zip ](samples/logs-api-tcp-response.zip)
****レスポンスコード****
+ 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` に書き出すログ。
+ 拡張機能 - 拡張コードが生成するログ。
+ プラットフォーム - ランタイムプラットフォームが生成するログ。呼び出しと拡張機能に関連するイベントおよびエラーを記録します。
**Topics**
+ [関数ログ](#runtimes-logs-api-msg-function)
+ [拡張ログ](#runtimes-logs-api-msg-extension)
+ [プラットフォームログ](#runtimes-logs-api-msg-platform)
### 関数ログ
Lambda 関数と内部拡張機能は、関数ログを生成し、`stdout` または `stderr` に書き出します。
次の例は、関数ログメッセージの形式を示しています。 \$1 "time": "2020-08-20T12:31:32.123Z", "type": "function", "record": "ERROR encountered。Stack trace:\$1n\$1my-function (line 10)\$1n" \$1
### 拡張ログ
拡張機能は、拡張ログを生成できます。ログ形式は、関数ログの場合と同じです。
### プラットフォームログ
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** ログメッセージには、[初期化ライフサイクルフェーズ](lambda-runtime-environment.md#runtimes-lifecycle-ib)の一部である `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"
}
```
**注記**
AWS は現在、Lambda サービスに変更を実装しています。これらの変更により、AWS アカウント のさまざまな Lambda 関数によって出力されるシステムログメッセージとトレースセグメントの構造と内容にわずかな違いが生じる場合があります。
この変更の影響を受けるログ出力の 1 つは、プラットフォームの障害ログ `"record"` フィールドです。次の例は、古い形式と新しい形式での `"record"` フィールドの例を示しています。新しいスタイルの障害ログには、より簡潔なメッセージが含まれています。
これらの変更は今後数週間に実装され、中国および GovCloud リージョンを除くすべての AWS リージョンのすべての関数は、新しい形式のログメッセージとトレースセグメントを使用するように移行されます。
**Example プラットフォーム障害ログレコード (古いスタイル)**
```
"record":"RequestId: ...\tError: Runtime exited with error: exit status 255\nRuntime.ExitError"
```
**Example プラットフォーム障害ログレコード (新しいスタイル)**
```
"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](samples/schema-2021-03-18.zip) から入手できます。
Lambda は、ランタイムが `Next` または `Error` ランタイム API リクエストを送信したときに `platform.runtimeDone` ログメッセージを生成します。`platform.runtimeDone` ログは、関数の呼び出しが完了したことを Logs API のコンシューマーに通知します。拡張機能は、この情報を使用して、呼び出し中に収集されたすべてのテレメトリをいつ送信するかを決定できます。
##### 例
Lambda は、関数の呼び出しが完了したときに、ランタイムが NEXT リクエストを送信した後に `platform.runtimeDone` メッセージを送信します。次の例は、各ステータス値 (成功、失敗、タイムアウト) のメッセージを示しています。
**Example 成功した場合のメッセージ例**
```
{
"time": "2021-02-04T20:00:05.123Z",
"type": "platform.runtimeDone",
"record": {
"requestId":"6f7f0961f83442118a7af6fe80b88",
"status": "success"
}
}
```
**Example 失敗した場合のメッセージ例**
```
{
"time": "2021-02-04T20:00:05.123Z",
"type": "platform.runtimeDone",
"record": {
"requestId":"6f7f0961f83442118a7af6fe80b88",
"status": "failure"
}
}
```
**Example タイムアウトした場合のメッセージ例**
```
{
"time": "2021-02-04T20:00:05.123Z",
"type": "platform.runtimeDone",
"record": {
"requestId":"6f7f0961f83442118a7af6fe80b88",
"status": "timeout"
}
}
```
**Example platform.restoreRuntimeDone メッセージの例 (`snap-start` 初期化タイプのみ)**
**platform.restoreRuntimeDone** ログメッセージには、`Restore` フェーズが正常に実行されたかどうかが表示されます。Lambda は、ランタイムが `restore/next` Runtime API リクエストを送信するときに、このメッセージを送信します。可能なステータスには、success (成功)、failure (失敗)、および timeout (タイムアウト) の 3 つがあります。以下は、正常に実行された **platform.restoreRuntimeDone** ログメッセージの例です。
```
{
"time":"2022-07-17T18:43:45.936Z",
"type":"platform.restoreRuntimeDone",
"record":{
"status":"success"
}
}
```