JSON とプレーンテキストのログフォーマットの設定

ログ出力を JSON キー値のペアとしてキャプチャすると、関数のデバッグ時の検索やフィルタリングが容易になります。JSON 形式のログでは、タグやコンテキスト情報をログに追加することもできます。これにより、大量のログデータを自動的に分析するのに役立ちます。開発ワークフローがプレーンテキストで Lambda ログを使用する既存のツールに依存している場合を除き、ログ形式には JSON を選択することをお勧めします。

すべての Lambda マネージドランタイムについて、関数のシステムログを CloudWatch Logs に非構造化プレーンテキストで送信するか、JSON 形式で送信するかを選択できます。システムログは Lambda が生成するログで、プラットフォームイベントログと呼ばれることもあります。

サポートされているランタイムでは、サポートされている組み込みログ記録メソッドのいずれかを使用すると、Lambda は関数のアプリケーションログ (関数コードが生成するログ) を構造化された JSON 形式で出力することもできます。これらのランタイムに対して関数のログ形式を設定すると、選択した設定がシステムログとアプリケーションログの両方に適用されます。

サポートされているランタイムでは、関数がサポートされているログ記録ライブラリまたはメソッドを使用している場合は、Lambda が構造化された JSON でログをキャプチャするために既存のコードを変更する必要はありません。

サポートされているランタイムとログ記録メソッド

Lambda は現在、以下のランタイムの JSON 構造化アプリケーションログを出力するオプションをサポートしています。

Lambda が関数のアプリケーションログを構造化された JSON 形式で CloudWatch に送信するには、関数が以下の組み込みログ記録ツールを使用してログを出力する必要があります。

サポートされているランタイムで高度なログ記録コントロールを使用する方法の詳細については、「Java Lambda 関数のログ記録とモニタリング」、「Node.js Lambda 関数のログ記録とモニタリング」および「Python Lambda 関数のログ記録とモニタリング」を参照してください。

他のマネージド Lambda ランタイムについては、現在、Lambda は構造化された JSON 形式でのシステムログのキャプチャのみをネイティブでサポートしています。ただし、Powertools for AWS Lambda などのログ記録ツールを使用して JSON 形式のログを出力することで、どのランタイムでも構造化 JSON 形式のアプリケーションログをキャプチャできます。

既定のログ形式

現在、すべての Lambda ランタイムのデフォルトのログ形式はプレーンテキストです。

既に Powertools for AWS Lambda などのログ記録ライブラリを使用して JSON 構造化形式で関数ログを生成している場合は、JSON ログ形式を選択すればコードを変更する必要はありません。Lambda は既に JSON でエンコードされたログを二重にエンコードしないため、関数のアプリケーションログは以前と同様にキャプチャされます。

システムログの JSON 形式

関数のログ形式を JSON として設定すると、各システムログ項目 (プラットフォームイベント) は、以下のキーを含むキー値のペアを含む JSON オブジェクトとしてキャプチャされます。

"record" 値の形式は、記録されるイベントのタイプによって異なります。詳細については、「Telemetry API Event オブジェクトタイプ」を参照してください。システムログイベントに割り当てられるログレベルの詳細については、「システムログレベルのイベントマッピング」を参照してください。

比較のため、以下の 2 つの例は、プレーンテキスト形式と構造化された JSON 形式の両方で同じログ出力を示しています。ほとんどの場合、システムログイベントには、プレーンテキストで出力される場合よりも JSON 形式で出力される方が多くの情報が含まれることに注意してください。

2024-03-13 18:56:24.046000 fbe8c1   INIT_START  Runtime Version: python:3.12.v18  Runtime Version ARN: arn:aws:lambda:eu-west-1::runtime:edb5a058bfa782cb9cedc6d534ac8b8c193bc28e9a9879d9f5ebaaf619cd0fc0

{
  "time": "2024-03-13T18:56:24.046Z",
  "type": "platform.initStart",
  "record": {
    "initializationType": "on-demand",
    "phase": "init",
    "runtimeVersion": "python:3.12.v18",
    "runtimeVersionArn": "arn:aws:lambda:eu-west-1::runtime:edb5a058bfa782cb9cedc6d534ac8b8c193bc28e9a9879d9f5ebaaf619cd0fc0"
  }
}

アプリケーションログの JSON 形式

関数のログ形式を JSON として設定すると、サポートされているログ記録ライブラリとメソッドを使用して書き込まれたアプリケーションログ出力は、以下のキーを持つキー値のペアを含む JSON オブジェクトとしてキャプチャされます。

関数が使用するランタイムとログ記録方法によっては、この JSON オブジェクトには追加のキーペアが含まれる場合もあります。例えば、Node.js では、関数が console メソッドを使用して複数の引数を使用しているエラーオブジェクトをログに記録する場合、JSON オブジェクトには、errorMessage、errorType、stackTrace というキーを含む追加のキーと値のペアが含まれます。さまざまな Lambda ランタイムの JSON 形式のログの詳細については、「Python Lambda 関数のログ記録とモニタリング、Node.js Lambda 関数のログ記録とモニタリング、Java Lambda 関数のログ記録とモニタリング」を参照してください。

比較のため、以下の 2 つの例は、プレーンテキスト形式と構造化された JSON 形式の両方で同じログ出力を示しています。

2024-10-27T19:17:45.586Z 79b4f56e-95b1-4643-9700-2807f4e68189 INFO some log message

{
    "timestamp":"2024-10-27T19:17:45.586Z",
    "level":"INFO",
    "message":"some log message",
    "requestId":"79b4f56e-95b1-4643-9700-2807f4e68189"
}

関数のログ形式の設定

関数のログ形式を設定するには、Lambda コンソールまたは AWS Command Line Interface (AWS CLI) を使用できます。CreateFunction と UpdateFunctionConfiguration Lambda API コマンド、AWS Serverless Application Model (AWS SAM) AWS::Serverless::Function リソース、および AWS CloudFormation AWS::Lambda::Function リソースを使用して、関数のログ形式を設定することもできます。

関数のログ形式を変更しても、CloudWatch Logs に保存されている既存のログには影響しません。新しいログのみが更新された形式を使用します。

関数のログ形式を JSON に変更し、ログレベルを設定しない場合、Lambda は関数のアプリケーションログレベルとシステムログレベルを自動的に INFO に設定します。つまり、Lambda はレベル INFO 以下のログ出力のみを CloudWatch Logs に送信します。アプリケーションおよびシステムログレベルのフィルタリングの詳細については、ログレベルのフィルタリング を参照してください。

埋め込みメトリックフォーマット (EMF、Embedded Metric Format) ログを生成する Node.js 関数の場合、関数のログ形式を JSON に変更すると、CloudWatch がメトリクスを認識できなくなる可能性があります。