配置汇总接收器

本文档介绍如何创建汇总接收器。如需了解如何管理现有接收器，请参阅配置和管理接收器。

概览

汇总接收器会合并和路由组织或文件夹包含的 Google Cloud 资源的日志条目。例如，您可以将组织包含的所有文件夹的审核日志条目汇总并路由到一个 Cloud Storage 存储桶。

如果没有聚合接收器功能，接收器只能从创建接收器的确切资源（Google Cloud 项目、组织、文件夹或结算帐号）中路由日志条目。

您可以为 Google Cloud 文件夹和组织创建汇总接收器。由于 Cloud 项目和结算帐号都不包含子资源，因此您无法为其创建汇总接收器。

支持的目标

您可以使用汇总接收器将相同组织和文件夹内或之间的日志路由到以下目标位置：

Cloud Storage：存储在 Cloud Storage 存储桶中的 JSON 文件。
Pub/Sub：传递给 Pub/Sub 主题的 JSON 消息。支持将 Splunk 等第三方服务与 Logging 集成。
BigQuery：在 BigQuery 数据集中创建的表。
另一个 Cloud Logging 存储桶：保存在 Cloud Logging 日志存储桶中的日志条目。

准备工作

在创建接收器之前，请确保满足以下条件：

您有一个 Google Cloud 文件夹或组织，其日志可在日志浏览器中查看。
对于您要从中路由日志的 Google Cloud 组织或文件夹，您拥有以下 IAM 角色之一。
- Owner (roles/owner)
- Logging Admin (roles/logging.admin)
- Logs Configuration Writer (roles/logging.configWriter)
这些角色中包含的权限可让您创建、删除或修改接收器。如需了解如何设置 IAM 角色，请参阅 Logging 访问权限控制指南。
您在受支持的目标位置中拥有资源，或者能够创建资源。

必须先通过 gcloud 命令行工具、Cloud Console 或 Google Cloud API 创建路由目标位置，然后再创建接收器。您可以在任何组织中的任何 Cloud 项目中创建目标位置，但需要确保接收器中的服务帐号具有向目标位置写入数据的权限。

创建汇总接收器

要使用汇总接收器，您需要在 Google Cloud 组织或文件夹中创建接收器，并将接收器的 includeChildren 参数设置为 True。然后，该接收器就可以从组织或文件夹中路由日志条目，也可以（以递归方式）从其包含的任何文件夹、结算帐号或 Cloud 项目中路由日志条目。您可以设置接收器的包含和排除过滤条件，以指定要路由到目标位置的日志条目。

每个文件夹或组织最多可以创建 200 个接收器。

要为文件夹或组织创建汇总接收器，请执行以下操作：

控制台

在 Cloud Console 中，转到 Logging > 日志路由器页面。

转到日志路由器
选择现有文件夹或组织。
选择创建接收器。
在接收器详情面板中，输入以下详细信息：
- 接收器名称：提供接收器的标识符。请注意，创建接收器后，您无法重命名接收器，但可以将其删除并创建新的接收器。
- 接收器说明（可选）：描述接收器的用途或使用场景。
在接收器目标位置面板中，选择接收器服务和目标位置：
- 选择接收器服务：选择您想要路由日志的目标服务。
根据您选择的服务，您可从以下目标位置中进行选择：
- Cloud Logging 存储桶：选择或创建 Logging 存储桶。
- BigQuery 表：选择或创建用于接收路由日志的特定数据集。您还可以选择使用分区表。
- Cloud Storage 存储桶：选择或创建用于接收路由日志的特定 Cloud Storage 存储桶。
- Pub/Sub 主题：选择或创建用于接收路由日志的特定主题。
- Splunk：为您的 Splunk 服务选择 Pub/Sub 主题。
  
  例如，如果接收器目标位置是 BigQuery 数据集，则接收器目标位置将如下所示：
```
bigquery.googleapis.com/projects/PROJECT_ID/datasets/DATASET_ID
```
在选择要包含在接收器中的日志面板中，执行以下操作：
1. 选择包含此资源和所有子资源注入的日志，这将创建汇总接收器。
2. 在构建包含项过滤条件字段中，输入与要包含的日志条目匹配的过滤条件表达式。如果您不设置过滤条件，来自所选资源的所有日志都会路由到目标位置。
  
  例如，您可能希望构建一个过滤条件，将所有数据访问日志都路由到单个 Logging 存储桶。此过滤条件大致如下所示：
```
LOG_ID("cloudaudit.googleapis.com/data_access") OR LOG_ID("externalaudit.googleapis.com/data_access")
```
  请注意，过滤条件的长度不能超过 20000 个字符。
3. 要验证您输入的过滤条件是否正确，请选择预览日志。此操作会在新的标签页中打开日志浏览器且其中预填充了过滤条件。
（可选）在选择要从接收器中排除的日志面板中，执行以下操作：
1. 在排除项过滤条件名称字段中输入名称。
2. 在构建排除项过滤条件部分，输入与要排除的日志条目匹配的过滤条件表达式。您还可以使用 sample 函数选择要排除的日志条目。
  
  要点：如果您希望在创建接收器时停用排除过滤器，请在输入过滤条件表达式后选择停用。您稍后可更新接收器来启用排除过滤器。
您最多可以为每个接收器创建 50 个排除过滤器。请注意，过滤条件的长度不能超过 20000 个字符。
选择创建接收器。

API

要创建接收器，请使用 Logging API 中的 organizations.sinks.create 或 folders.sinks.create。请按以下步骤准备方法的参数：

将 parent 参数设置为要在其中创建接收器的 Google Cloud 组织或文件夹。parent 参数必须是以下之一：
- organizations/ORGANIZATION_ID
- folders/FOLDER_ID
在方法请求正文中的 LogSink 对象中，执行以下操作：
- 将 includeChildren 设置为 True。
- 设置 filter 属性。请注意，过滤条件的长度不能超过 20000 个字符。
  
  如需查看一些实用过滤条件示例，请参阅为聚合接收器创建过滤条件。
- 像设置任何接收器一样设置其余 LogSink 字段。如需了解详情，请参阅配置和管理接收器。
调用 organizations.sinks.create 或 folders.sinks.create 以创建接收器。
从 API 响应返回的 writer_identity 字段中检索服务帐号名称。
授权该服务帐号向接收器目标位置写入内容。

如果您无权对接收器目标位置进行更改，请将该服务帐号名称发送给可以代您执行更改的人员。

如需详细了解如何为资源授予服务帐号权限，请参阅设置目标位置权限部分。

gcloud

要创建接收器，请使用 logging sinks create 命令。

提供接收器名称、接收器目标位置、过滤条件以及您要从中路由日志的文件夹或组织的 ID：
```
gcloud logging sinks create SINK_NAME
SINK_DESTINATION  --include-children \
--folder=FOLDER_ID filter
```
例如，如果您在文件夹级层创建汇总接收器，并且其目标位置是 BigQuery 数据集，则您的命令可能如下所示：
```
gcloud logging sinks create SINK_NAME \
bigquery.googleapis.com/projects/PROJECT_ID/datasets/DATASET_ID --include-children \
--folder=FOLDER_ID --log-filter="logName:activity"
```
注意：
- 如需在组织级层创建接收器，请将 --folder=FOLDER_ID 替换为 --organization=ORGANIZATION_ID。
- 如需让接收器包含组织内的所有资源，必须设置 --include-children 标志，即使 --organization 标志传递给 create 也是如此。如果将此标志设置为 false（默认值），接收器将仅从主机资源路由日志。
- 如需查看一些实用过滤条件示例，请参阅为聚合接收器创建过滤条件。
从命令输出中检索用于创建接收器的服务帐号名称。
授权该服务帐号向接收器目标位置写入内容。

如果您无权对接收器目标位置进行更改，请将该服务帐号名称发送给可以代您执行更改的人员。

如需详细了解如何为资源授予服务帐号权限，请参阅设置目标位置权限部分。

为汇总接收器创建过滤条件

与任何接收器一样，汇总接收器中包含一个用于选择单个日志条目的过滤条件。如需了解可用于创建汇总接收器的过滤条件示例，请参阅使用日志浏览器的查询示例。

以下是一些在使用汇总接收器功能时有用的过滤条件比较示例。部分示例使用以下表示法：

: 是子字符串运算符。请勿将其替换为 = 运算符。
... 表示任何其他过滤条件比较。
变量用彩色文本表示。请用有效值替换变量。

请注意，过滤条件的长度不能超过 20000 个字符。

如需详细了解过滤语法，请参阅日志记录查询语言。

选择日志源

如需路由来自特定 Cloud 项目、文件夹或组织的日志，请使用以下示例比较之一：

logName:"projects/PROJECT_ID/logs/" AND ...

logName:("projects/PROJECT_A_ID/logs/" OR "projects/PROJECT_B_ID/logs/") AND ...

logName:"folders/FOLDER_ID/logs/" AND ...

logName:"organizations/ORGANIZATION_ID/logs/" AND ...

选择受监控的资源

如仅需从 Cloud 项目中的特定受监控的资源路由日志，请使用多项比较来准确指定资源：

logName:"projects/PROJECT_ID/logs" AND
resource.type=RESOURCE_TYPE AND
resource.labels.instance_id=INSTANCE_ID

如需查看资源类型的列表，请参阅受监控的资源类型。

选择日志条目示例

如需路由随机选取的日志条目，请添加 sample 内置函数。例如，要仅路由与当前过滤条件匹配的 10% 的日志条目，请使用以下添加函数：

sample(insertId, 0.10) AND ...

如需了解详情，请参阅 sample 函数。

如需详细了解 Cloud Logging 过滤条件，请参阅日志记录查询语言。

设置目标位置权限

本部分介绍如何向 Logging 授予将日志写入接收器目标位置的 Identity and Access Management 权限。如需查看 Logging 角色和权限的完整列表，请参阅访问权限控制。

当您创建接收器后，Logging 会为该接收器创建一个新的服务帐号（称为唯一写入者身份）。您的接收器目标位置必须允许此服务帐号写入日志条目。您无法直接管理此服务帐号，因为它由 Cloud Logging 拥有和管理。如果接收器被删除，则此服务帐号也会被删除。

如需将日志路由到受服务边界保护的资源，您必须将该接收器的服务帐号添加到某个访问权限级别，然后将其分配给目标服务边界。对于非汇总接收器，则无需执行此操作。如需了解详情，请参阅 VPC Service Controls：Cloud Logging。

如需设置便于接收器路由到其目标位置的权限，请执行以下操作：

控制台

从新接收器获取接收器的写入者身份，也就是一个电子邮件地址。转到日志路由器页面，然后选择菜单 > 查看接收器详情。写入者身份会显示在接收器详情面板中。
如果您拥有对目标位置的 Owner 访问权限，则按以下方式将服务帐号添加到目标位置：
- 对于 Cloud Storage 目标位置，将接收器的写入者身份添加到 Cloud Storage 存储桶，并为其指定 Storage Object Creator 角色。
- 对于 BigQuery 目标位置，将接收器的写入者身份添加到数据集，并为其提供 BigQuery Data Editor 角色。
- 对于 Pub/Sub（包括 Splunk），将接收器的写入者身份添加到您的主题，并为其指定 Pub/Sub Publisher 角色。
- 对于不同 Cloud 项目中的 Logging 存储桶目标位置，将接收器的写入者身份添加到目标存储桶，并为其授予 roles/logging.bucketWriter 权限。
如果您没有接收器目标位置的 Owner 访问权限，请将具有写入者身份的服务帐号名称发送给具有该访问能力的人员。然后，该人员应按照上一步骤中的说明将写入者身份添加到接收器目标位置。

API

通过调用 API 方法 organizations.sinks.get 或 folders.sinks.get，从接收器中的 writerIdentity 字段获取服务帐号。

服务帐号格式类似于以下内容：
```
serviceAccount:p123456789012-12345@gcp-sa-logging.iam.gserviceaccount.com
```
将新接收器的写入者身份添加到目标位置的权限列表，授予写入者向目标位置写入的权限。

如果您拥有对目标位置的 IAM Owner 访问权限，请按以下方式将服务帐号添加到目标位置：
- 对于 Cloud Storage 目标位置，将接收器的写入者身份添加到 Cloud Storage 存储桶，并为其指定 Storage Object Creator 角色。
- 对于 BigQuery 目标位置，将接收器的写入者身份添加到数据集，并为其提供 BigQuery Data Editor 角色。
- 对于 Cloud Pub/Sub，含 Splunk，将接收器的写入者身份添加到您的主题，并为其指定 Pub/Sub Publisher 角色。
- 对于不同 Cloud 项目中的 Logging 存储桶目标位置，将接收器的写入者身份添加到目标日志存储桶，并为其授予 roles/logging.bucketWriter 权限。
如果您没有接收器目标位置的 Owner 访问权限，请将具有写入者身份的服务帐号名称发送给具有该访问能力的人员。然后，该人员应按照上一步骤中的说明将写入者身份添加到接收器目标位置。

gcloud

从新接收器获取接收器的写入者身份，也就是一个电子邮件地址：

从接收器中的 writerIdentity 字段获取服务帐号：

gcloud logging sinks describe SINK_NAME

服务帐号格式类似于以下内容：

serviceAccount:p123456789012-12345@gcp-sa-logging.iam.gserviceaccount.com

如果您拥有对目标位置的 IAM Owner 访问权限，请按以下方式将服务帐号添加到目标位置：
- 对于 Cloud Storage 目标位置，将接收器的写入者身份添加到 Cloud Storage 存储桶，并为其指定 Storage Object Creator 角色。
- 对于 BigQuery 目标位置，将接收器的写入者身份添加到数据集，并为其提供 BigQuery Data Editor 角色。
- 对于 Pub/Sub（包括 Splunk），将接收器的写入者身份添加到您的主题，并为其指定 Pub/Sub Publisher 角色。
- 对于不同 Cloud 项目中的 Logging 存储桶目标位置，将接收器的写入者身份添加到目标日志存储桶，并为其授予 roles/logging.bucketWriter 权限。
如果您没有接收器目标位置的 Owner 访问权限，请将具有写入者身份的服务帐号名称发送给具有该访问能力的人员。然后，该人员应按照上一步骤中的说明将写入者身份添加到接收器目标位置。

例如，如果您要在不同 Cloud 项目中的 Logging 存储桶之间路由日志，应将 roles/logging.bucketWriter 添加到服务帐号，如下所示：
1. 获取目标 Cloud 项目的 Identity and Access Management 政策，并将其写入 JSON 格式的本地文件：
```
gcloud projects get-iam-policy DESTINATION_PROJECT_ID --format json > output.json
```
2. 添加一个 IAM 条件，仅允许服务帐号写入您创建的目的地。例如：
```
{
"bindings": [
 {
   "members": [
     "user:username@gmail.com"
   ],
   "role": "roles/owner"
 },
 {
   "members": [
     "SERVICE_ACCOUNT"
   ],
   "role": "roles/logging.bucketWriter",
   "condition": {
       "title": "Bucket writer condition example",
       "description": "Grants logging.bucketWriter role to service account SERVICE_ACCOUNT used by sink SINK_NAME",
       "expression":
         "resource.name.endsWith(\'locations/global/buckets/BUCKET_ID\')"
   }
 }
],
"etag": "BwWd_6eERR4=",
"version": 3
}
```
  注意：如果您尚未在政策中使用 IAM 条件，则可能需要更改版本。请务必指定版本 3。如需了解政策版本，请查看 IAM 文档中的了解政策部分。
3. 更新 IAM 政策：
```
gcloud projects set-iam-policy DESTINATION_PROJECT_ID output.json
```

后续步骤

如需了解如何管理现有接收器，请参阅配置和管理接收器。
如果您在使用接收器来路由日志时遇到问题，请参阅排查路由和接收器问题。
如需了解如何在目标位置查看路由的日志，以及日志的格式和组织方式，请参阅查看接收器目标位置中的日志。