# 日志级别筛选
<a name="monitoring-cloudwatchlogs-log-level"></a>

Lambda 可以筛选函数的日志，以便仅将不超过特定详细信息级别的日志发送到 CloudWatch Logs。您可以分别为函数的系统日志（Lambda 生成的日志）和应用程序日志（您的函数代码生成的日志）单独配置日志级别筛选。

对于 [支持的运行时系统和日志记录方法](monitoring-cloudwatchlogs-logformat.md#monitoring-cloudwatchlogs-logformat-supported)，要筛选函数的应用程序日志，无需对 Lambda 的函数代码进行任何更改。

对于所有其他运行时系统和日志记录方法，您的函数代码必须将日志事件作为 JSON 格式的对象输出到 `stdout` 或 `stderr`，并在其中包含键 `"level"` 的键值对。例如，Lambda 将以下到 `stdout` 的输出解释为调试级别的日志。

```
print('{"level": "debug", "msg": "my debug log", "timestamp": "2024-11-02T16:51:31.587199Z"}')
```

如果 `"level"` 值字段无效或缺失，Lambda 将为日志输出分配 INFO 级别。要让 Lambda 使用时间戳字段，您必须以有效的 [RFC 3339](https://www.ietf.org/rfc/rfc3339.txt) 时间戳格式指定时间。如果您未提供有效的时间戳，Lambda 将为日志分配 INFO 级别并为您添加时间戳。

命名时间戳键时，请遵循所用运行时系统的惯例。Lambda 支持托管运行时系统使用的大多数常用命名惯例。

**注意**  
要使用日志级别筛选，必须将您的函数配置为使用 JSON 日志格式。目前，所有 Lambda 托管运行时系统的默认日志格式均为纯文本。要了解如何将函数的日志格式配置为 JSON，请参阅 [设置函数的日志格式](monitoring-cloudwatchlogs-logformat.md#monitoring-cloudwatchlogs-set-format)。

对于应用程序日志（由函数代码生成的日志），您可以从以下日志级别中进行选择。


| 日志级别 | 标准使用情况 | 
| --- | --- | 
| TRACE（最详细） | 用于跟踪代码执行路径的最精细信息 | 
| 调试 | 系统调试的详细信息 | 
| INFO | 记录函数正常运行情况的消息 | 
| 警告 | 有关潜在错误的消息，如果不加以解决，这些错误可能会导致意外行为 | 
| ERROR | 有关会阻碍代码按预期执行的问题的消息 | 
| FATAL（最简略） | 有关导致应用程序停止运行的严重错误的消息 | 

当您选择日志级别后，Lambda 会将该级别及更低级别的日志发送到 CloudWatch Logs。例如，如果您将函数的应用程序日志级别设置为 WARN，则 Lambda 不会发送 INFO 和 DEBUG 级别的日志输出。日志筛选的默认应用程序日志级别为 INFO。

当 Lambda 筛选函数的应用程序日志时，将为没有级别的日志消息分配日志级别 INFO。

对于系统日志（由 Lambda 服务生成的日志），您可以在以下日志级别之间进行选择。


| 日志级别 | 用法 | 
| --- | --- | 
| DEBUG（最详细） | 系统调试的详细信息 | 
| INFO | 记录函数正常运行情况的消息 | 
| WARN（最简略） | 有关潜在错误的消息，如果不加以解决，这些错误可能会导致意外行为 | 

当您选择日志级别后，Lambda 会发送该级别及更低级别的日志。例如，如果您将函数的系统日志级别设置为 INFO，则 Lambda 不会发送 DEBUG 级别的日志输出。

默认情况下，Lambda 会将系统日志级别设置为 INFO。使用此设置，Lambda 会自动向 CloudWatch 发送 `"start"` 和 `"report"` 日志消息。要接收不同详细程度的系统日志，请将日志级别更改为 DEBUG 或 WARN。要查看 Lambda 将不同系统日志事件映射到的日志级别列表，请参阅 [系统日志级别的事件映射](#monitoring-cloudwatchlogs-log-level-mapping)。

## 配置日志级别筛选
<a name="monitoring-cloudwatchlogs-log-level-setting"></a>

要为您的函数配置应用程序和系统日志级别的筛选，您可以使用 Lambda 控制台或 Amazon Command Line Interface（Amazon CLI）。您还可以使用 [CreateFunction](https://docs.amazonaws.cn/lambda/latest/api/API_CreateFunction.html) 和 [UpdateFunctionConfiguration](https://docs.amazonaws.cn/lambda/latest/api/API_UpdateFunctionConfiguration.html) Lambda API 命令、Amazon Serverless Application Model（Amazon SAM）[AWS::Serverless::Function](https://docs.amazonaws.cn/serverless-application-model/latest/developerguide/sam-resource-function.html) 资源以及 Amazon CloudFormation [AWS::Lambda::Function](https://docs.amazonaws.cn/AWSCloudFormation/latest/UserGuide/aws-resource-lambda-function.html) 资源来配置函数的日志级别。

请注意，如果在代码中设置函数的日志级别，则此设置将优先于您配置的任何其他日志级别设置。例如，如果您通过 Python `logging` `setLevel()` 方法将函数的日志级别设置为 INFO，则此设置将优先于您通过 Lambda 控制台配置的 WARN 设置。

**配置现有函数的应用程序或系统日志级别（控制台）**

1. 打开 Lamba 控制台的[函数](https://console.amazonaws.cn/lambda/home#/functions)页面。

1. 选择函数。

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

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

1. 在**日志内容**下，确保为**日志格式**选择 **JSON**。

1. 使用单选按钮，为您的函数选择所需的**应用程序日志级别**和**系统日志级别**。

1. 选择**保存**。

**配置现有函数的应用程序或系统日志级别（Amazon CLI）**
+ 要更改现有函数的应用程序或系统日志级别，请使用 [update-function-configuration](https://awscli.amazonaws.com/v2/documentation/api/latest/reference/lambda/update-function-configuration.html) 命令。使用 `--logging-config` 将 `SystemLogLevel` 设为 `DEBUG`、`INFO` 或 `WARN`。将 `ApplicationLogLevel` 设置为 `DEBUG`、`INFO`、`WARN`、`ERROR` 或 `FATAL` 之一。

  ```
  aws lambda update-function-configuration \
    --function-name myFunction \
    --logging-config LogFormat=JSON,ApplicationLogLevel=ERROR,SystemLogLevel=WARN
  ```

**在创建函数时配置日志级别筛选**
+ 要在创建新函数时配置日志级别筛选，请在 [create-function](https://awscli.amazonaws.com/v2/documentation/api/latest/reference/lambda/create-function.html) 命令中使用 `--logging-config` 来设置 `SystemLogLevel` 和 `ApplicationLogLevel` 键。将 `SystemLogLevel` 设置为 `DEBUG`、`INFO` 或 `WARN` 之一。将 `ApplicationLogLevel` 设置为 `DEBUG`、`INFO`、`WARN`、`ERROR` 或 `FATAL` 之一。

  ```
  aws lambda create-function \
    --function-name myFunction \
    --runtime nodejs24.x \
    --handler index.handler \
    --zip-file fileb://function.zip \
    --role arn:aws:iam::123456789012:role/LambdaRole \ 
    --logging-config LogFormat=JSON,ApplicationLogLevel=ERROR,SystemLogLevel=WARN
  ```

## 系统日志级别的事件映射
<a name="monitoring-cloudwatchlogs-log-level-mapping"></a>

对于 Lambda 生成的系统级日志事件，下表定义了分配给每个事件的日志级别。要了解有关表中所列事件的更多信息，请参阅 [Lambda 遥测 API `Event` 架构参考](telemetry-schema-reference.md)


| 事件名称 | 条件 | 分配的日志级别 | 
| --- | --- | --- | 
| initStart | 已设置 runtimeVersion | INFO | 
| initStart | 未设置 runtimeVersion | 调试 | 
| initRuntimeDone | status=success | 调试 | 
| initRuntimeDone | status\$1=success | 警告 | 
| initReport | initializationType\$1=on-demand | INFO | 
| initReport | initializationType=on-demand | 调试 | 
| initReport | status\$1=success | 警告 | 
| restoreStart | 已设置 runtimeVersion | INFO | 
| restoreStart | 未设置 runtimeVersion | 调试 | 
| restoreRuntimeDone | status=success | 调试 | 
| restoreRuntimeDone | status\$1=success | 警告 | 
| restoreReport | status=success | INFO | 
| restoreReport | status\$1=success | 警告 | 
| 开启 | - | INFO | 
| runtimeDone | status=success | 调试 | 
| runtimeDone | status\$1=success | 警告 | 
| 报告 | status=success | INFO | 
| 报告 | status\$1=success | 警告 | 
| extension | state=success | INFO | 
| extension | state\$1=success | 警告 | 
| logSubscription | - | INFO | 
| telemetrySubscription | - | INFO | 
| logsDropped | - | 警告 | 

**注意**  
[使用遥测 API 访问扩展的实时遥测数据](telemetry-api.md) 始终会发出一整套平台事件。配置 Lambda 发送到 CloudWatch 的系统日志的级别不会影响 Lambda 遥测 API 的行为。

## 使用自定义运行时系统进行应用程序日志级别筛选
<a name="monitoring-cloudwatchlogs-log-level-custom"></a>

当您为函数配置应用程序日志级别筛选时，Lambda 会在后台使用 `AWS_LAMBDA_LOG_LEVEL` 环境变量在运行时系统中设置应用程序日志级别。Lambda 还会使用 `AWS_LAMBDA_LOG_FORMAT` 环境变量设置函数的日志格式。您可以使用这些变量将 Lambda 高级日志记录控件集成到[自定义运行时系统](runtimes-custom.md)中。

要使用自定义运行时系统通过 Lambda 控制台、Amazon CLI 和 Lambda API 为函数配置日志记录设置，请配置您的自定义运行时系统以检查这些环境变量的值。然后，您可以根据所选的日志格式和日志级别配置运行时系统的记录器。