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

本文档介绍如何创建汇总接收器。通过汇总接收器 合并和路由由 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。

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

  • 为服务边界指定入站流量或出站流量政策时 您不能使用 ANY_SERVICE_ACCOUNT 和 使用日志接收器时，将 ANY_USER_ACCOUNT 作为身份类型 将日志路由到 Cloud Storage 资源。 不过，您可以使用 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 项目中 但您必须确保 接收器具有写入目标位置的权限。

创建汇总接收器

控制台

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

  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

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

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

  10. 选择创建接收器。

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

协议

如需创建汇总接收器，请使用 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. 向接收器授予向接收器写入服务账号的权限 目标。如需了解详情，请参阅设置目标位置权限。

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. 向接收器的服务账号授予向接收器目标位置写入内容的权限。如需了解详情，请参阅 设置目标位置权限。

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

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

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

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

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

请注意，过滤条件的长度不能超过 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 项目，请使用多个比较项来指定资源 确切：

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 日之前，Logging 创建了一项服务 每个接收器均分配一个账号自 2023 年 5 月 22 日起，Logging 将为底层资源中的所有接收器使用共享服务账号。

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

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

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

控制台

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

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

      前往日志路由器

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

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

    3. 如果 writerIdentity 字段的值包含电子邮件地址， 然后继续下一步如果值为 None，则无需配置目标权限。

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

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

    5. 将服务账号添加为 目标项目：

      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 权限。

协议

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

gcloud

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

  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)。
      • 对于位于不同目标位置的 Logging 存储桶目标位置 Google Cloud 项目，请通过以下命令将接收器的写入者身份添加为主账号 使用 IAM，然后为其授予 Logs Bucket Writer 角色 (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

后续步骤