整理组织级和文件夹级日志，并将其路由到支持的目标位置

本文档介绍如何创建汇总接收器。借助汇总接收器，您可以将组织或文件夹中的 Google Cloud 资源生成的日志合并并路由到一个集中位置。

概览

汇总接收器会合并组织或文件夹所含资源的日志条目，并将其路由到目标位置。

如果您想控制可以在这些资源中查询哪些日志，或者通过这些资源中的接收器路由哪些日志，则可以将汇总接收器配置为非拦截或拦截：

  • 非拦截汇总接收器通过子资源中的接收器路由日志。借助此接收器，您可以在生成日志的资源中持续查看日志。非拦截接收器对子资源不可见。

    例如，您可以创建非拦截汇总接收器，将组织所含文件夹中生成的所有日志条目路由到一个 Cloud Storage 中央存储分区。这些日志存储在中央 Cloud Storage 存储桶中，也存储在生成日志的资源中。

  • 拦截汇总接收器会阻止日志通过子资源中的接收器路由（_Required 接收器除外）。此接收器有助于防止将日志的重复副本存储在多个位置。

    以数据访问审核日志为例，该日志的数量庞大，而且存储多个副本的费用很高。如果您启用了数据访问审核日志，则可以创建一个文件夹级拦截接收器，将所有数据访问审核日志路由到一个中央项目进行分析。 这种拦截接收器还可以防止子资源中的接收器将日志副本路由到其他位置。

    拦截接收器会阻止日志通过子资源的日志路由器传递，除非日志也与 _Required 接收器匹配。由于日志被拦截，因此日志不会计入子资源中基于日志的指标或基于日志的提醒中。您可以在子资源的日志路由器页面中查看拦截接收器的接收器。

如需了解如何管理接收器，请参阅将日志路由到支持的目标位置：管理接收器。

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

支持的目标

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

  • Cloud Logging 存储桶：在 Cloud Logging 中提供存储空间。 日志存储桶可以存储多个 Google Cloud 项目收到的日志条目。您可以将 Cloud Logging 数据与其他数据合并，方法是升级日志存储桶以使用 Log Analytics，然后创建关联的 BigQuery 数据集。如需了解如何查看存储在日志存储分区中的日志条目，请参阅查询和查看日志概览和查看路由到 Cloud Logging 存储分区的日志。
  • BigQuery 数据集：提供 BigQuery 数据集中日志条目的存储服务。您可以对存储的日志条目使用大数据分析功能。如需将 Cloud Logging 数据与其他数据源相结合，我们建议您升级日志存储分区以使用 Log Analytics，然后创建关联的 BigQuery 数据集。如需了解如何查看路由到 BigQuery 的日志条目，请参阅查看路由到 BigQuery 的日志。
  • Cloud Storage 存储桶：在 Cloud Storage 中提供日志条目的存储。日志条目以 JSON 文件的形式存储。如需了解如何查看路由到 Cloud Storage 的日志条目，请参阅查看路由到 Cloud Storage 的日志。
  • Pub/Sub 主题：为第三方集成提供支持。日志条目会格式化为 JSON，然后路由到 Pub/Sub 主题。如需了解如何查看路由到 Pub/Sub 的日志条目，请参阅查看路由到 Pub/Sub 的日志。
  • Splunk：为 Splunk 提供支持。 您必须将日志条目路由到某个 Pub/Sub 主题，然后使用 Splunk 订阅该主题。
  • Google Cloud 项目：将日志条目路由到其他 Google Cloud 项目。当您将日志条目路由到其他 Google Cloud 项目时，目标项目的日志路由器会接收并处理日志条目。目标项目中的接收器决定了收到的日志条目的路由方式。当目标项目将日志条目路由到目标项目拥有的日志存储桶时，Error Reporting 可以分析这些日志条目。
  • 其他资源：将日志条目路由到其他项目中的受支持目标位置。如需了解要使用的路径，请参阅目标路径格式。

拦截接收器的最佳实践

创建拦截接收器时，我们建议您执行以下操作：

  • 考虑子资源是否需要独立控制其日志的路由。如果子资源需要单独控制某些日志，请确保拦截接收器不会路由这些日志。

  • 在拦截接收器的说明中添加联系信息。如果管理拦截接收器的人员与管理日志被拦截项目的人员不同，这种做法可能很有用。

  • 测试接收器配置，首先创建一个非拦截的汇总接收器，确保路由正确的日志。

汇总接收器和 VPC Service Controls

使用汇总接收器和 VPC Service Controls 时，存在以下限制：

  • 汇总接收器可以访问服务边界内的项目的数据。如需限制汇总接收器访问边界内的数据，我们建议使用 IAM 管理 Logging 权限。

  • VPC Service Controls 不支持向服务边界添加文件夹或组织资源。因此，您无法使用 VPC Service Controls 来保护文件夹级和组织级日志，包括聚合日志。如需在文件夹级或组织级管理 Logging 权限，建议使用 IAM。

  • 如果您使用文件夹级或组织级接收器将日志路由到服务边界保护的资源，则必须向服务边界添加入站规则。入站规则必须允许从汇总接收器使用的服务帐号访问资源。如需了解详情，请参阅以下页面：

  • 为服务边界指定入站流量或出站流量政策后，在使用日志接收器将日志路由到 Cloud Storage 资源时，不能使用 ANY_SERVICE_ACCOUNT 和 ANY_USER_ACCOUNT 作为身份类型。不过，您可以使用 ANY_IDENTITY 作为身份类型。

准备工作

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

  • 您有一个 Google Cloud 文件夹或组织，其日志可在日志浏览器中查看。

  • 对于您要从中路由日志的 Google Cloud 组织或文件夹，您拥有以下 IAM 角色之一。

    • Owner (roles/owner)
    • Logging Admin (roles/logging.admin)
    • Logs Configuration Writer (roles/logging.configWriter)

    这些角色中包含的权限可让您创建、删除或修改接收器。如需了解如何设置 IAM 角色，请参阅 Logging 访问权限控制指南。

  • 您在受支持的目标位置中拥有资源，或者能够创建资源。

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

创建汇总接收器

如需创建非拦截汇总接收器，您需要在 Google Cloud 组织或文件夹中创建接收器，并将接收器的 includeChildren 参数设置为 True。设置 includeChildren 参数后，接收器会路由来自组织或文件夹的日志条目，以及（以递归方式）从其包含的任何文件夹、结算帐号或 Google Cloud 项目路由日志条目。如需创建拦截接收器，请将 includeChildren 和 interceptChildren 参数均设置为 True。

如需指定要路由到目标位置的日志条目，请设置接收器的包含和排除过滤条件。

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

控制台

  1. 在 Google Cloud 控制台的导航面板中，选择 Logging，然后选择日志路由器：

    前往日志路由器

  2. 选择现有文件夹或组织。

  3. 选择创建接收器。

  4. 在接收器详情面板中，输入以下详细信息：

    • 接收器名称：提供接收器的标识符。请注意，创建接收器后，您无法重命名接收器，但可以将其删除并创建新的接收器。

    • 接收器说明（可选）：描述接收器的用途或使用场景。

  5. 在接收器目标位置面板中，选择接收器服务和目标位置：

    • 选择接收器服务：选择要将日志路由到的服务。如果您要创建拦截接收器，则只能选择 Google Cloud 项目作为目标位置。

    根据您选择的服务，您可从以下目标位置中进行选择：

    • Cloud Logging 存储桶：选择或创建 Logging 存储桶。如果您要创建日志存储桶，它必须位于项目级。您无法在文件夹或组织级层创建日志存储桶。
    • BigQuery 表：选择或创建用于接收路由日志的特定数据集。您还可以选择使用分区表。
    • Cloud Storage 存储桶：选择或创建用于接收路由日志的特定 Cloud Storage 存储桶。
    • Pub/Sub 主题：选择或创建用于接收路由日志的特定主题。
    • Splunk：为您的 Splunk 服务选择 Pub/Sub 主题。

    • Google Cloud 项目：选择用于接收路由日志的 Google Cloud 项目。

      例如，如果接收器目标位置是 BigQuery 数据集，则接收器目标位置将如下所示：

      bigquery.googleapis.com/projects/PROJECT_ID/datasets/DATASET_ID

  6. 在选择要包含在接收器中的日志面板中，执行以下操作之一：

    • 如需创建非拦截汇总接收器，请选择包括此资源和所有子资源提取的日志。

    • 如需创建拦截接收器，请选择拦截此组织和所有子资源注入的日志。

  7. 在构建包含过滤器字段中输入与要包含的日志条目匹配的过滤表达式，完成对话框。如果您未设置过滤条件，则所选资源中的所有日志都将路由到目标位置。

    例如，您可能希望构建一个过滤条件，将所有数据访问审核日志路由到单个 Logging 存储桶。此过滤条件如下所示：

    LOG_ID("cloudaudit.googleapis.com/data_access") OR LOG_ID("externalaudit.googleapis.com/data_access")

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

  8. （可选）如需验证您输入的过滤条件是否正确，请选择预览日志。系统将在新标签页中打开日志浏览器，其中已预填充过滤条件。

  9. （可选）在选择要从接收器中排除的日志面板中，执行以下操作：

    1. 在排除项过滤条件名称字段中输入名称。

    2. 在构建排除项过滤条件部分，输入与要排除的日志条目匹配的过滤条件表达式。您还可以使用 sample 函数选择要排除的日志条目。

      例如，如需排除来自特定项目的日志，使其不路由到目标位置，请添加以下排除过滤条件：

      logName:projects/PROJECT_ID

      如需排除来自多个项目的日志，请使用逻辑或运算符连接 logName 子句。

    您最多可以为每个接收器创建 50 个排除过滤器。请注意，过滤条件的长度不能超过 20000 个字符。

  10. 选择创建接收器。

API

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

  1. 将 parent 参数设置为要在其中创建接收器的 Google Cloud 组织或文件夹。parent 参数必须是以下之一：

    • organizations/ORGANIZATION_ID
    • folders/FOLDER_ID

  2. 在方法请求正文的 LogSink 对象中，执行以下操作之一：

    • 如需创建非拦截汇总接收器，请将 includeChildren 设置为 True。

    • 如需创建拦截接收器，请将 includeChildren 和 interceptChildren 参数设置为 True。

  3. 设置 filter 属性，使其与您要添加的日志条目相匹配。请注意，过滤条件的长度不能超过 20000 个字符。

    如需查看一些实用过滤条件示例，请参阅为聚合接收器创建过滤条件。

  4. 像设置任何接收器一样设置其余 LogSink 字段。如需了解详情，请参阅将日志路由到支持的目标位置。

  5. 调用 organizations.sinks.create 或 folders.sinks.create 以创建接收器。

  6. 从 API 响应返回的 writer_identity 字段中检索服务账号名称。

  7. 授权该服务账号向接收器目标位置写入内容。

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

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

gcloud

如需创建汇总接收器，请使用 logging sinks create 命令。如需创建非拦截汇总接收器，请指定 --include-children 标志。如需创建拦截接收器，请同时指定 --include-children 和 --intercept-children 标志。

  1. 提供接收器名称、接收器目标位置、过滤条件以及要从其中路由日志的文件夹或组织的 ID：以下示例会创建一个非拦截的汇总接收器：

    gcloud logging sinks create SINK_NAME \
  SINK_DESTINATION  --include-children \
  --folder=FOLDER_ID --log-filter="LOG_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（默认值），接收器将仅从主机资源路由日志。

    • 如需查看一些实用过滤条件示例，请参阅为聚合接收器创建过滤条件。

  2. 从命令输出中检索用于创建接收器的服务账号名称。

  3. 授权该服务账号向接收器目标位置写入内容。

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

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

对接收器所做的任何更改可能需要几分钟才能应用。

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

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

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

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

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

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

选择日志源

对于汇总接收器，对于组织或文件夹的每个子资源，接收器的包含和排除过滤条件将应用于发送到子资源的每个日志条目。系统会路由与包含项过滤条件匹配且未排除的日志条目。

如果您希望接收器路由来自所有子资源的日志，请勿在接收器的包含和排除过滤条件中指定项目、文件夹或组织。例如，假设您使用以下过滤条件为组织配置汇总接收器：

resource.type="gce_instance"

使用上述过滤条件后，具有 Compute Engine 实例资源类型且写入该组织的任何子级的日志会由聚合接收器路由到目标位置。

但是，在某些情况下，您可能希望使用汇总接收器仅从特定子资源路由日志。例如，出于合规性原因，您可能希望将来自特定文件夹或项目的审核日志存储在其自己的 Cloud Storage 存储桶中。在这些情况下，您可以配置包含过滤器，以指定您要路由其日志的每个子资源。如果要从文件夹及其中的所有项目路由日志，则过滤条件必须列出该文件夹及其包含的每个项目，并且还使用 OR 子句连接语句。

以下过滤条件将日志限制为特定 Google 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 ...

例如，如需仅路由写入到 Compute Engine 实例并写入 my-folder 文件夹的日志，请使用以下过滤条件：

logName:"folders/my-folder/logs/" AND resource.type="gce_instance"

使用上述过滤条件时，写入到 my-folder 以外的任何资源的日志（包括写入 Google Cloud 项目的作为 my-folder 子项的日志）都不会路由到目标位置。

选择受监控的资源

如需仅从 Google 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 会自动为您创建和管理服务帐号：

  • 自 2023 年 5 月 22 日起，当您创建接收器且没有底层资源的服务帐号时，Logging 会创建服务帐号。Logging 对底层资源中的所有接收器使用相同的服务帐号。资源可以是 Google Cloud 项目、组织、文件夹或结算帐号。
  • 在 2023 年 5 月 22 日之前，Logging 会为每个接收器创建一个服务帐号。自 2023 年 5 月 22 日起，Logging 会为底层资源中的所有接收器使用共享服务帐号。

接收器的写入者身份是与该接收器关联的服务帐号的标识符。所有接收器都具有写入者身份，除非它们向当前 Google Cloud 项目中的日志存储桶写入数据。

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

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

控制台

  1. 如需获取有关接收器的服务帐号的信息，请执行以下操作：

    1. 在 Google Cloud 控制台的导航面板中，选择 Logging，然后选择日志路由器：

      前往日志路由器

    2. 选择 菜单，然后选择查看接收器详情。

      在接收器详情面板中，writerIdentity 字段包含服务帐号的身份。serviceAccount: 字符串是服务帐号身份的一部分。例如：

      serviceAccount:service-123456789012@gcp-sa-logging.iam.gserviceaccount.com

  2. 在目标项目中，向写入者身份授予服务帐号向目标位置写入数据所需的角色。如需向主帐号授予角色，您必须拥有 Owner (roles/owner) 角色：

    • 对于 Cloud Storage 目标位置，请使用 IAM 将接收器的写入者身份添加为主帐号，然后向其授予 Storage Object Creator 角色 (roles/storage.objectCreator)。
    • 对于 BigQuery 目标位置，请使用 IAM 将接收器的写入者身份添加为主帐号，然后向其授予 BigQuery Data Editor 角色 (roles/bigquery.dataEditor)。
    • 对于 Pub/Sub 目标位置（包括 Splunk），请使用 IAM 将接收器的写入者身份添加为主帐号，然后向其授予 Pub/Sub Publisher 角色 (roles/pubsub.publisher)。
    • 对于不同 Google Cloud 项目中的 Logging 存储桶目标位置，请使用 IAM 将接收器的写入者身份添加为主帐号，然后向其授予 Logs Bucket Writer 角色 (roles/logging.bucketWriter)。
    • 对于 Google Cloud 项目目标位置，请使用 IAM 将接收器的写入者身份添加为主账号，然后向其授予 Logs Writer 角色 (roles/logging.logWriter)。具体而言，主账号需要 logging.logEntries.route 权限。
    如果您没有对接收器目标位置的 Owner 访问权限，则可以请求项目所有者将写入者身份添加为主帐号。

API

  1. 如需获取有关接收器的服务帐号的信息，请调用 API 方法 organizations.sinks.get 或 folders.sinks.get。

    writerIdentity 字段包含服务帐号的身份。serviceAccount: 字符串是服务帐号身份的一部分。例如：

    serviceAccount:service-123456789012@gcp-sa-logging.iam.gserviceaccount.com

  2. 在目标项目中，向写入者身份授予服务帐号向目标位置写入数据所需的角色。如需向主帐号授予角色，您必须拥有 Owner (roles/owner) 角色：

    • 对于 Cloud Storage 目标位置，请使用 IAM 将接收器的写入者身份添加为主帐号，然后向其授予 Storage Object Creator 角色 (roles/storage.objectCreator)。
    • 对于 BigQuery 目标位置，请使用 IAM 将接收器的写入者身份添加为主帐号，然后向其授予 BigQuery Data Editor 角色 (roles/bigquery.dataEditor)。
    • 对于 Pub/Sub 目标位置（包括 Splunk），请使用 IAM 将接收器的写入者身份添加为主帐号，然后向其授予 Pub/Sub Publisher 角色 (roles/pubsub.publisher)。
    • 对于不同 Google Cloud 项目中的 Logging 存储桶目标位置，请使用 IAM 将接收器的写入者身份添加为主帐号，然后向其授予 Logs Bucket Writer 角色 (roles/logging.bucketWriter)。
    • 对于 Google Cloud 项目目标位置，请使用 IAM 将接收器的写入者身份添加为主账号，然后向其授予 Logs Writer 角色 (roles/logging.logWriter)。具体而言，主账号需要 logging.logEntries.route 权限。
    如果您没有对接收器目标位置的 Owner 访问权限，则可以请求项目所有者将写入者身份添加为主帐号。

gcloud

  1. 如需获取有关接收器的服务帐号的信息，请运行以下命令：

    gcloud logging sinks describe SINK_NAME

    writerIdentity 字段包含服务帐号的身份。serviceAccount: 字符串是服务帐号身份的一部分。例如：

    serviceAccount:service-123456789012@gcp-sa-logging.iam.gserviceaccount.com

  2. 在目标项目中，向写入者身份授予服务帐号向目标位置写入数据所需的角色。如需向主帐号授予角色，您必须拥有 Owner (roles/owner) 角色：

    • 对于 Cloud Storage 目标位置，请使用 IAM 将接收器的写入者身份添加为主帐号，然后向其授予 Storage Object Creator 角色 (roles/storage.objectCreator)。
    • 对于 BigQuery 目标位置，请使用 IAM 将接收器的写入者身份添加为主帐号，然后向其授予 BigQuery Data Editor 角色 (roles/bigquery.dataEditor)。
    • 对于 Pub/Sub 目标位置（包括 Splunk），请使用 IAM 将接收器的写入者身份添加为主帐号，然后向其授予 Pub/Sub Publisher 角色 (roles/pubsub.publisher)。
    • 对于不同 Google Cloud 项目中的 Logging 存储桶目标位置，请使用 IAM 将接收器的写入者身份添加为主帐号，然后向其授予 Logs Bucket Writer 角色 (roles/logging.bucketWriter)。
    • 对于 Google Cloud 项目目标位置，请使用 IAM 将接收器的写入者身份添加为主账号，然后向其授予 Logs Writer 角色 (roles/logging.logWriter)。具体而言，主账号需要 logging.logEntries.route 权限。
    如果您没有对接收器目标位置的 Owner 访问权限，则可以请求项目所有者将写入者身份添加为主帐号。

后续步骤