# 配置 CloudWatch 日志组
<a name="monitoring-cloudwatchlogs-loggroups"></a>

默认情况下，CloudWatch 会在首次调用您的函数时为其自动创建一个名为 `/aws/lambda/<function name>` 的日志组。要将您的函数配置为向现有日志组发送日志，或者为函数创建新的日志组，可以使用 Lambda 控制台或 AWS CLI。您还可以使用 [CreateFunction](https://docs.aws.amazon.com/lambda/latest/api/API_CreateFunction.html) 和 [UpdateFunctionConfiguration](https://docs.aws.amazon.com/lambda/latest/api/API_UpdateFunctionConfiguration.html) Lambda API 命令以及 AWS Serverless Application Model（AWS SAM）[AWS::Serverless::Function]() 资源配置自定义日志组。

您可以配置多个 Lambda 函数向同一 CloudWatch 日志组发送日志。例如，您可以使用单个日志组来存储构成特定应用程序的所有 Lambda 函数的日志。当您为 Lambda 函数使用自定义日志组时，Lambda 创建的日志流包括函数名称和函数版本。这可以确保即使将同一个日志组用于多个函数，也能保留日志消息与函数之间的映射。

自定义日志组的日志流命名格式遵循以下惯例：

```
YYYY/MM/DD/<function_name>[<function_version>][<execution_environment_GUID>]
```

请注意，配置自定义日志组时，您为日志组选择的名称必须遵守 [CloudWatch Logs 命名规则](https://docs.aws.amazon.com/AmazonCloudWatchLogs/latest/APIReference/API_CreateLogGroup.html)。此外，自定义日志组名称不得以字符串 `aws/` 开头。如果以 `aws/` 为开头创建自定义日志组，则 Lambda 将无法创建该日志组。这将导致函数的日志不会发送到 CloudWatch。

**更改函数的日志组（控制台）**

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

1. 选择函数。

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

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

1. 在**日志记录组**窗格中，为 **CloudWatch 日志组**选择**自定义**。

1. 在**自定义日志组**下，输入您希望函数发送日志的目标 CloudWatch 日志组的名称。如果您输入现有日志组的名称，则函数将使用该组。如果不存在具有所输入名称的日志组，则 Lambda 将使用该名称为您的函数创建一个新的日志组。

**更改函数的日志组（AWS CLI）**
+ 要更改现有函数的日志组，请使用 [update-function-configuration](https://awscli.amazonaws.com/v2/documentation/api/latest/reference/lambda/update-function-configuration.html) 命令。

  ```
  aws lambda update-function-configuration \
    --function-name myFunction \
    --logging-config LogGroup=myLogGroup
  ```

**在创建函数时指定自定义日志组（AWS CLI）**
+ 要在使用 AWS CLI 创建新 Lambda 函数时指定自定义日志组，请使用 `--logging-config` 选项。以下示例命令可创建 Node.js Lambda 函数，用于将日志发送到名为 `myLogGroup` 的日志组。

  ```
  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 LogGroup=myLogGroup
  ```

## 执行角色权限
<a name="monitoring-cloudwatchlogs-configure-permissions"></a>

您的函数必须拥有 [logs:PutLogEvents](https://docs.aws.amazon.com/AmazonCloudWatchLogs/latest/APIReference/API_PutLogEvents.html) 权限，才能向 CloudWatch Logs 发送日志。当您使用 Lambda 控制台配置函数的日志组时，Lambda 将在以下条件下将此权限添加到角色：
+ 服务目标设置为 CloudWatch Logs
+ 函数的执行角色没有将日志上传到 CloudWatch Logs（默认目标）的权限

**注意**  
Lambda 不会为 Amazon S3 或 Firehose 日志目标添加任何 Put 权限。

当 Lambda 添加此权限时，它会向该函数授予向任何 CloudWatch Logs 日志组发送日志的权限。

要防止 Lambda 自动更新函数的执行角色并改为手动对其进行编辑，请展开**权限**并取消选中**添加所需权限**。

当您使用 AWS CLI 配置函数的日志组时，Lambda 不会自动添加 `logs:PutLogEvents` 权限。如果函数的执行角色还没有该权限，请添加。此权限包含在 [AWSLambdaBasicExecutionRole](https://console.aws.amazon.com/iam/home#/policies/arn:aws:iam::aws:policy/service-role/AWSLambdaBasicExecutionRole$jsonEditor) 托管策略中。

## Lambda 托管实例的 CloudWatch 日志记录
<a name="monitoring-cloudwatchlogs-lmi"></a>

使用 [Lambda 托管实例](lambda-managed-instances.md)时，在将日志发送至 CloudWatch Logs 时还需注意以下事项：

### VPC 联网要求
<a name="monitoring-cloudwatchlogs-lmi-networking"></a>

Lambda 托管实例在您的 VPC 内的客户自有 EC2 实例上运行。要将日志发送到 CloudWatch Logs 并将跟踪发送到 X-Ray，您必须确保这些 AWS API 可以从您的 VPC 路由。您有多种选择：
+ **AWS PrivateLink（推荐）**：使用 [AWS PrivateLink](https://docs.aws.amazon.com/vpc/latest/privatelink/what-is-privatelink.html) 为 CloudWatch Logs 和 X-Ray 服务创建 VPC 端点。这使得您的实例能够以私有方式访问这些服务，而无需使用互联网网关或 NAT 网关。有关更多信息，请参阅[将 CloudWatch Logs 与接口 VPC 端点结合使用](https://docs.aws.amazon.com/AmazonCloudWatch/latest/logs/cloudwatch-logs-and-interface-VPC.html)。
+ **NAT 网关**：配置 NAT 网关以允许从您的私有子网中进行出站互联网访问。
+ **互联网网关**：对于公有子网，请确保您的 VPC 已配置互联网网关。

如果 CloudWatch Logs 或 X-Ray API 无法从您的 VPC 进行路由，则您的函数日志和跟踪将无法传输。

### 并发调用和日志归因
<a name="monitoring-cloudwatchlogs-lmi-concurrent"></a>

Lambda 托管实例执行环境可以同时处理多个调用。当多个调用同时运行时，它们的日志条目会交错出现在同一个日志流中。为了有效地筛选和分析来自并发调用的日志，您应当确保每个日志条目都包含 AWS 请求 ID。

我们推荐采用以下方法之一：
+ **使用默认的 Lambda 运行时记录器（推荐）**：Lambda 托管运行时提供的默认日志记录库会自动在每个日志条目中包含请求 ID。
+ **实施结构化 JSON 日志记录**：如果您正在构建[自定义运行时](runtimes-custom.md)或需要自定义日志记录，请实施在每个条目中包含请求 ID 的 JSON 格式日志。Lambda 托管实例仅支持 JSON 日志格式。在 JSON 日志中包含 `requestId` 字段以启用按调用进行筛选：

  ```
  {
    "timestamp": "2025-01-15T10:30:00.000Z",
    "level": "INFO",
    "requestId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "message": "Processing request"
  }
  ```

借助请求 ID 归因，您可以使用 CloudWatch Logs Insights 查询筛选特定调用的 CloudWatch Logs 日志条目。例如：

```
fields @timestamp, @message
| filter requestId = "a1b2c3d4-e5f6-7890-abcd-ef1234567890"
| sort @timestamp asc
```

有关 Lambda 托管实例日志记录要求的更多信息，请参阅 [了解 Lambda 托管实例执行环境](lambda-managed-instances-execution-environment.md)。