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

本文档介绍如何创建汇总接收器。如需了解如何管理现有接收器，请参阅将日志路由到受支持的目标位置：管理接收器。

概览

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

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

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

支持的目标

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

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

须知事项

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

  • 您有一个 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。然后，该接收器可以从组织或文件夹路由日志条目，也可以（以递归方式）从其包含的任何文件夹、结算帐号或 Google Cloud 项目中路由日志条目。您可以设置接收器的包含和排除过滤条件，以指定要路由到目标位置的日志条目。

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

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

控制台

  1. 在 Google Cloud 控制台中，选择 Logging，然后选择日志路由器，或点击以下按钮：

    转到日志路由器

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

  3. 选择创建接收器。

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

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

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

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

    • 选择接收器服务：选择您想要路由日志的目标服务。

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

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

    • Splunk：为您的 Splunk 服务选择 Pub/Sub 主题。

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

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

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

    1. 选择包含此资源和所有子资源注入的日志，这将创建汇总接收器。

    2. 在构建包含项过滤条件字段中，输入与要包含的日志条目匹配的过滤条件表达式。如果您不设置过滤条件，来自所选资源的所有日志都会路由到目标位置。

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

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

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

    3. 要验证您输入的过滤条件是否正确，请选择预览日志。此操作会在新的标签页中打开日志浏览器且其中预填充了过滤条件。

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

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

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

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

      logName:projects/PROJECT_ID

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

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

  8. 选择创建接收器。

API

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

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

    • organizations/ORGANIZATION_ID
    • folders/FOLDER_ID

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

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

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

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

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

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

gcloud

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

  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 个字符。

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

选择日志源

如需路由来自特定 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 ...

选择受监控的资源

如需仅从 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 访问权限，则可以请求项目所有者将写入者身份添加为主帐号。

后续步骤