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

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

概览

汇总接收器会合并和路由组织或文件夹包含的资源的日志条目到目的地。

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

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

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

  • 拦截汇总接收器可防止日志条目通过子资源中的接收器（_Required 接收器除外）进行路由。此接收器对于防止日志条目的重复副本存储在多个位置非常有用。

    例如，请考虑数据访问审核日志，其可能非常庞大，并且存储多个副本的费用很高。如果您已启用数据访问审核日志，则可以创建文件夹级拦截接收器，将所有数据访问审核日志路由到中央项目进行分析。此拦截接收器还可防止子资源中的接收器将日志的副本路由到其他位置。

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

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

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

支持的目标

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

  • Cloud Logging 存储桶：在 Cloud Logging 中提供存储空间。日志桶可以存储多个 Google Cloud 项目收到的日志条目。日志存储桶可以位于日志条目来源的项目中，也可以位于其他项目中。如需了解如何查看存储在日志存储分区中的日志条目，请参阅查询和查看日志概览以及查看路由到 Cloud Logging 存储分区的日志。

    您可以通过以下方式将 Cloud Logging 数据与其他数据组合：升级日志存储桶以使用 Log Analytics，然后创建关联的数据集（这是一个只读数据集，可通过 BigQuery Studio 和 Looker Studio 页面进行查询）。

  • BigQuery 数据集：在可写入的 BigQuery 数据集中提供日志条目的存储空间。BigQuery 数据集可以位于日志条目来源的项目中，也可以位于其他项目中。您可以对存储的日志条目使用大数据分析功能。如需了解如何查看路由到 BigQuery 的日志条目，请参阅查看路由到 BigQuery 的日志。

  • Cloud Storage 存储桶：在 Cloud Storage 中提供日志条目的存储空间。Cloud Storage 存储桶可以位于日志条目来源的项目中，也可以位于其他项目中。日志条目存储为 JSON 文件。如需了解如何查看转送到 Cloud Storage 的日志条目，请参阅查看转送到 Cloud Storage 的日志。

  • Pub/Sub 主题：提供对第三方集成的支持。日志条目会转换为 JSON 格式，然后路由到 Pub/Sub 主题。主题可以位于日志条目来源的项目中，也可以位于其他项目中。如需了解如何查看路由到 Pub/Sub 的日志条目，请参阅查看路由到 Pub/Sub 的日志。

  • Google Cloud 项目：将日志条目路由到另一个 Google Cloud 项目。在此配置中，目标项目中的接收器会处理日志条目。

拦截接收器的最佳实践

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

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

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

  • 请先创建一个非拦截汇总接收器，以测试接收器配置，确保系统正在路由正确的日志条目。

汇总的接收器和 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 项目中创建目标位置，但必须确保接收器中的服务账号具有向目标位置写入数据的权限。

  • Select the tab for how you plan to use the samples on this page:

    Console

    When you use the Google Cloud console to access Google Cloud services and APIs, you don't need to set up authentication.

    gcloud

    In the Google Cloud console, activate Cloud Shell.

    Activate Cloud Shell

    At the bottom of the Google Cloud console, a Cloud Shell session starts and displays a command-line prompt. Cloud Shell is a shell environment with the Google Cloud CLI already installed and with values already set for your current project. It can take a few seconds for the session to initialize.

    REST

    如需在本地开发环境中使用本页面上的 REST API 示例，请使用您提供给 gcloud CLI 的凭据。

      Install the Google Cloud CLI, then initialize it by running the following command: 

      gcloud init

    如需了解详情，请参阅 Google Cloud 身份验证文档中的使用 REST 时进行身份验证。

创建汇总接收器

控制台

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

  1. 在 Google Cloud 控制台中，转到日志路由器页面：

    前往日志路由器

    如果您使用搜索栏查找此页面，请选择子标题为 Logging 的结果。

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

  3. 选择创建接收器。

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

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

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

  5. 执行下列其中一项操作：

    • 如需创建拦截接收器，请在选择接收器服务菜单中，选择 Google Cloud 项目，然后输入目的地的完全限定名称。如需了解语法，请参阅目标路径格式。

    • 如需创建非拦截式接收器，请前往选择接收器服务菜单，然后执行以下操作之一：

      • 如需将日志条目路由到其他 Google Cloud 项目，请选择 Google Cloud 项目，然后输入目标的完全限定名称。如需了解语法，请参阅目标路径格式。

      • 如需将日志条目路由到同一 Google Cloud 项目中的服务，请选择以下选项之一：

        • BigQuery 数据集：选择或创建用于接收路由日志条目的特定数据集。您还可以选择使用分区表。
        • Cloud Storage 存储桶：选择或创建用于接收路由日志条目的特定 Cloud Storage 存储桶。
        • Pub/Sub 主题：选择或创建用于接收路由日志条目的特定主题。
        • Splunk：为您的 Splunk 服务选择 Pub/Sub 主题。

      • 如需将日志条目路由到位于其他 Google Cloud 项目中的服务，请执行以下操作：

        1. 选择其他资源。

        2. 输入目的地的完全限定名称。如需了解语法，请参阅目标路径格式。

          例如，如果您的接收器目标位置是 Pub/Sub 主题，则 destination 如下所示：

          pubsub.googleapis.com/projects/PROJECT_ID/topics/TOPIC_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

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

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

  10. 选择创建接收器。

  11. 向接收器的服务账号授予向接收器目标位置写入日志条目的权限。如需了解详情，请参阅设置目标位置权限。

gcloud

如需创建汇总接收器，请使用 logging sinks create 命令：

  1. 如需创建接收器，请调用 gcloud logging sinks create 命令，并确保添加 --include-children 选项。

    在使用以下命令之前，请先进行以下替换：

    • SINK_NAME：日志接收器的名称。数据流接收器一经创建便无法更改其名称。
    • SINK_DESTINATION：您希望将日志条目路由到的服务或项目。
    • INCLUSION_FILTER：接收器的包含项过滤条件。如需查看过滤条件示例，请参阅为汇总接收器创建过滤条件。
    • FOLDER_ID：文件夹的 ID。如果您想在组织级层创建接收器，请将 --folder=FOLDER_ID 替换为 -- organization=ORGANIZATION_ID。

    执行 gcloud logging sinks create 命令：

    gcloud logging sinks create SINK_NAME \
  SINK_DESTINATION  --include-children \
  --folder=FOLDER_ID --log-filter="INCLUSION_FILTER"

    您还可以提供以下选项：

    • 如需创建拦截接收器，请添加 --intercept-children 选项。

    例如，如果您在文件夹级层创建汇总接收器，并且其目标位置是 Pub/Sub 主题，则您的命令可能如下所示：

    gcloud logging sinks create SINK_NAME \
  pubsub.googleapis.com/projects/PROJECT_ID/topics/TOPIC_ID --include-children \
  --folder=FOLDER_ID --log-filter="logName:activity"

  2. 向接收器的服务账号授予向接收器目标位置写入内容的权限。如需了解详情，请参阅设置目标位置权限。

REST

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

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

    • organizations/ORGANIZATION_ID
    • folders/FOLDER_ID

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

    • 将 includeChildren 设置为 True。

    • 如需创建拦截接收器，还应将 interceptChildren 字段设置为 True。

  3. 设置 filter 字段，使其与要包含的日志条目匹配。

    如需查看过滤条件示例，请参阅为汇总接收器创建过滤条件。

    过滤条件的长度不能超过 20,000 个字符。

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

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

  6. 向接收器的服务账号授予向接收器目标位置写入内容的权限。如需了解详情，请参阅设置目标位置权限。

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

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

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

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

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

请注意，过滤条件的长度不能超过 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 以外的任何资源（包括写入 my-folder 的子 Google Cloud 项目）的日志条目都不会路由到目的地。

选择受监控的资源

如仅需从 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 会创建服务账号。日志记录会对底层资源中的所有接收器使用相同的服务账号。资源可以是 Google Cloud 项目、组织、文件夹或结算账号。
  • 在 2023 年 5 月 22 日之前，日志记录功能会为每个接收器创建一个服务账号。自 2023 年 5 月 22 日起，Logging 将为底层资源中的所有接收器使用共享服务账号。

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

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

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

控制台

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

    1. 在 Google Cloud 控制台中，转到日志路由器页面：

      前往日志路由器

      如果您使用搜索栏查找此页面，请选择子标题为 Logging 的结果。

    2. 选择 Menu，然后选择查看接收器详情。写入者身份会显示在接收器详情面板中。

    3. 如果 writerIdentity 字段的值包含电子邮件地址，请继续执行下一步。当值为 None 时，您无需配置目标位置权限。

    4. 将接收器的写入者身份复制到剪贴板。 serviceAccount: 字符串是服务账号身份的一部分。例如：

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

    5. 在目标项目中将服务账号添加为 IAM 正文：

      1. 在 Google Cloud 控制台中，进入 IAM 页面：

        前往 IAM

        如果您使用搜索栏查找此页面，请选择子标题为 IAM 和管理的结果。

      2. 选择目标项目。

      3. 点击 授予访问权限。

      4. 向服务账号授予所需的 IAM 角色：

        • 对于 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 将接收器的写入者身份添加为正文，然后为其授予“日志存储桶写入者”角色 (roles/logging.bucketWriter)。
        • 对于 Google Cloud 项目目的地，请使用 IAM 将接收器的写入者身份添加为正文，然后向其授予 Logs Writer 角色 (roles/logging.logWriter)。具体而言，正文需要拥有 logging.logEntries.route 权限。

gcloud

  1. 确保您对包含目标位置的 Google Cloud 项目拥有 Owner 访问权限。如果您没有对接收器目标位置的 Owner 访问权限，请让项目所有者将写入者身份添加为正文。

  2. 如需获取有关接收器服务账号的信息，请调用 gcloud logging sinks describe 方法。

    在使用以下命令之前，请先进行以下替换：

    • SINK_NAME：日志接收器的名称。数据流接收器一经创建便无法更改其名称。

    执行 gcloud logging sinks describe 命令：

    gcloud logging sinks describe SINK_NAME

  3. 如果接收器详情包含标记为 writerIdentity 的字段，请继续执行下一步。如果详细信息不包含 writerIdentity 字段，则无需为接收器配置目标位置权限。

  4. 将接收器的写入者身份复制到剪贴板。 serviceAccount: 字符串是服务账号身份的一部分。

    服务账号的写入者身份类似于以下内容：

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

  5. 如需将服务账号添加为目标项目中的 IAM 正文，请调用 gcloud projects add-iam-policy-binding 命令。

    在使用以下命令之前，请先进行以下替换：

    • PROJECT_ID：项目的标识符。
    • PRINCIPAL：您要授予该角色的主账号的标识符。主账号标识符通常采用以下格式：PRINCIPAL-TYPE:ID。例如 user:my-user@example.com。 如需查看 PRINCIPAL 可采用的格式的完整列表，请参阅主账号标识符。

    • ROLE：IAM 角色。

      • 对于 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 将接收器的写入者身份添加为正文，然后为其授予“日志存储桶写入者”角色 (roles/logging.bucketWriter)。
      • 对于 Google Cloud 项目目的地，请使用 IAM 将接收器的写入者身份添加为正文，然后向其授予 Logs Writer 角色 (roles/logging.logWriter)。具体而言，正文需要拥有 logging.logEntries.route 权限。

    执行 gcloud projects add-iam-policy-binding 命令：

    gcloud projects add-iam-policy-binding PROJECT_ID --member=PRINCIPAL --role=ROLE

REST

我们建议您使用 Google Cloud 控制台或 Google Cloud CLI 向服务账号授予角色。

后续步骤