配置 JSON 和纯文本日志格式 - Amazon Lambda
支持的运行时系统和日志记录方法默认日志格式系统日志的 JSON 格式应用程序日志的 JSON 格式设置函数的日志格式
Amazon Web Services 文档中描述的 Amazon Web Services 服务或功能可能因区域而异。要查看适用于中国区域的差异，请参阅 中国的 Amazon Web Services 服务入门 (PDF)。

配置 JSON 和纯文本日志格式

将日志输出捕获为 JSON 键值对，可以更轻松地在调试函数时进行搜索和筛选。使用 JSON 格式的日志，您还可以在日志中添加标签和上下文信息。这可以帮助您对大量日志数据执行自动分析。除非您的开发工作流程依赖于使用纯文本格式 Lambda 日志的现有工具，否则我们建议您为日志格式选择 JSON。

对于所有 Lambda 托管的运行时系统，您可以选择将函数的系统日志以非结构化纯文本格式还是 JSON 格式发送到 CloudWatch Logs。系统日志是由 Lambda 生成的日志，有时也被称为平台事件日志。

对于支持的运行时系统，当您使用支持的内置日志记录方法之一时，Lambda 还能以结构化的 JSON 格式输出函数的应用程序日志（您的函数代码生成的日志）。当您为这些运行时系统配置函数的日志格式时，您选择的配置将同时应用于系统日志和应用程序日志。

对于支持的运行时系统，如果您的函数使用支持的日志库或方法，则无需对 Lambda 的现有代码进行任何更改，即可在结构化的 JSON 中捕获日志。

注意

使用 JSON 日志格式可以添加额外的元数据，并将日志消息编码为包含一系列键值对的 JSON 对象。因此，函数日志消息的大小可能会增加。

支持的运行时系统和日志记录方法

Lambda 目前支持为以下运行时系统输出 JSON 结构化应用程序日志的选项。

运行时 支持的版本
Java Amazon Linux 1 上除 Java 8 之外的所有 Java 运行时系统
.NET .NET 8
Node.js Node.js 16 及更高版本
Python Python 3.8 及更高版本

为了让 Lambda 以结构化的 JSON 格式将函数的应用程序日志发送到 CloudWatch，您的函数必须使用以下内置日志记录工具来输出日志：

  • Java - LambdaLogger 记录器或 Log4j2。

  • .NET：上下文对象上的 ILambdaLogger 实例。

  • Node.js - 控制台方法 console.trace、console.debug、console.log、console.info、console.error 和 console.warn

  • Python - 标准 Python logging 库

有关在支持的运行时系统中使用高级日志记录控件的更多信息，请参阅 Java Lambda 函数日志记录和监控、Node.js Lambda 函数日志记录和监控 和 Python Lambda 函数日志记录和监控。

对于其他托管 Lambda 运行时系统，Lambda 本身目前仅支持以结构化的 JSON 格式捕获系统日志。但是，您仍然可以在任何运行时系统中使用输出 JSON 格式日志输出的日志记录工具（例如 Powertools for Amazon Lambda），以结构化的 JSON 格式捕获应用程序日志。

默认日志格式

目前，所有 Lambda 运行时系统的默认日志格式均为纯文本。

如果您已经在使用像 Powertools for Amazon Lambda 这样的日志库来生成 JSON 结构化格式的函数日志，则在选择 JSON 日志格式后无需更改代码。Lambda 不会对任何已采用 JSON 编码的日志进行双重编码，因此仍将像以前一样捕获函数的应用程序日志。

系统日志的 JSON 格式

当您将函数的日志格式配置为 JSON 时，每个系统日志项（平台事件）都将被捕获为一个 JSON 对象，并且包含带有以下键的键值对：

  • "time" - 生成日志消息的时间

  • "type" - 正在记录的事件类型

  • "record" - 日志输出的内容

"record" 值的格式因所记录的事件类型而异。有关更多信息，请参阅 遥测 API Event 对象类型。有关分配给系统日志事件的日志级别的更多信息，请参阅 系统日志级别的事件映射。

为了进行比较，以下两个示例以纯文本和结构化的 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
例 结构化的 JSON：
{
  "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"
  }
}
注意

使用遥测 API 访问扩展的实时遥测数据 始终以 JSON 格式发出平台事件，例如 START 和 REPORT。配置 Lambda 发送到 CloudWatch 的系统日志的格式不会影响 Lambda 遥测 API 的行为。

应用程序日志的 JSON 格式

当您将函数的日志格式配置为 JSON 时，使用支持的日志记录库和方法编写的应用程序日志输出将被捕获为 JSON 对象，其中包含带有以下键的键值对。

  • "timestamp" - 生成日志消息的时间

  • "level" - 分配给消息的日志级别

  • "message" - 日志消息的内容

  • "requestId"（Python、.NET 和 Node.js）或 "AWSrequestId"（Java）：函数调用的唯一请求 ID

根据函数使用的运行时系统和日志记录方法，此 JSON 对象还可能包含其他密钥对。例如，在 Node.js 中，如果函数通过 console 方法使用多个参数记录错误对象，则 JSON 对象将包含带有键 errorMessage、errorType、和 stackTrace 的额外键值对。要了解有关不同 Lambda 运行时系统中的 JSON 格式日志的更多信息，请参阅 Python Lambda 函数日志记录和监控、Node.js Lambda 函数日志记录和监控 和 Java Lambda 函数日志记录和监控。

注意

对于系统日志和应用程序日志，Lambda 用于时间戳值的键不同。对于系统日志，Lambda 使用密钥 "time" 来与遥测 API 保持一致。对于应用程序日志，Lambda 遵循支持的运行时系统并使用 "timestamp" 的惯例。

为了进行比较，以下两个示例以纯文本和结构化的 JSON 格式显示了相同的日志输出。

例 纯文本：
2024-10-27T19:17:45.586Z 79b4f56e-95b1-4643-9700-2807f4e68189 INFO some log message
例 结构化的 JSON：
{
    "timestamp":"2024-10-27T19:17:45.586Z",
    "level":"INFO",
    "message":"some log message",
    "requestId":"79b4f56e-95b1-4643-9700-2807f4e68189"
}

设置函数的日志格式

要配置函数的日志格式，您可以使用 Lambda 控制台或 Amazon Command Line Interface（Amazon CLI）。您还可以使用 CreateFunction 和 UpdateFunctionConfiguration Lambda API 命令、Amazon Serverless Application Model（Amazon SAM）AWS::Serverless::Function 资源以及 Amazon CloudFormation AWS::Lambda::Function 资源来配置函数的日志格式。

更改函数的日志格式不会影响 CloudWatch Logs 中存储的现有日志。只有新的日志才会使用更新的格式。

如果您将函数的日志格式更改为 JSON 且未设置日志级别，则 Lambda 会自动将函数的应用程序日志级别和系统日志级别设置为 INFO。这意味着 Lambda 仅向 CloudWatch Logs 发送 INFO 及以下级别的日志输出。要了解有关应用程序和系统日志级别筛选的更多信息，请参阅 日志级别筛选

注意

对于 Python 运行时系统，当函数的日志格式设置为纯文本时，默认的日志级别设置为 WARN。这意味着 Lambda 仅向 CloudWatch Logs 发送 WARN 及以下级别的日志输出。将函数的日志格式更改为 JSON 可更改此默认行为。要了解有关 Python 中的日志记录的更多信息，请参阅 Python Lambda 函数日志记录和监控。

对于发出嵌入式指标格式（EMF）日志的 Node.js 函数，将函数的日志格式更改为 JSON 可能会导致 CloudWatch 无法识别您的指标。

重要

如果您的函数使用 Powertools for Amazon Lambda（TypeScript）或开源的 EMF 客户端库来发出 EMF 日志，请将 Powertools 和 EMF 库更新到最新版本，以确保 CloudWatch 能够继续正确解析您的日志。如果您切换到 JSON 日志格式，我们还建议您进行测试以确保与函数的嵌入式指标兼容。有关发出 EMF 日志的 node.js 函数的更多建议，请参阅 使用带有结构化的 JSON 日志的嵌入式指标格式（EMF）客户端库。

配置函数的日志格式（控制台）

  1. 打开 Lamba 控制台的函数页面。

  2. 选择函数

  3. 在函数配置页面上，选择监控和操作工具。

  4. 在日志记录配置窗格中，选择编辑。

  5. 在日志内容下，为日志格式选择文本或 JSON。

  6. 选择保存。

要更改现有函数的日志格式（Amazon CLI）

  • 要更改现有函数的日志格式，请使用 update-function-configuration 命令。将 LoggingConfig 中的 LogFormat 选项设置为 JSON 或 Text。

    aws lambda update-function-configuration \
  --function-name myFunction \
  --logging-config LogFormat=JSON
要在创建函数时设置日志格式（Amazon CLI）

  • 要在创建新函数时配置日志格式，请使用 create-function 命令中的 --logging-config 选项。将 LogFormat 设置为 JSON 或 Text。以下示例命令创建 Node.js 函数，该函数以结构化 JSON 格式输出日志。

    如果您在创建函数时未指定日志格式，Lambda 将使用您选择的运行时系统版本的默认日志格式。有关默认日志记录格式的信息，请参阅 默认日志格式。

    aws lambda create-function \ 
  --function-name myFunction \ 
  --runtime nodejs22.x \
  --handler index.handler \
  --zip-file fileb://function.zip \
  --role arn:aws:iam::123456789012:role/LambdaRole \
  --logging-config LogFormat=JSON