创建和管理日志范围

本文档介绍了如何创建和管理日志范围（您可以使用日志范围来帮助您高效查找要查看或分析的日志条目）。如果您只想查看和分析源自项目、文件夹或组织的日志条目，则本文档不适合您。不过，如果您依靠日志接收器将日志路由到其他项目或用户定义的日志存储桶，或者如果您使用日志视图，本文档中的信息可能会帮助您高效地查找特定日志条目。

本文档未介绍如何查看日志。如需了解该主题，请参阅使用 Logs Explorer 查看日志。

日志范围简介

日志范围是列出一组资源的项目级永久性资源。这些资源可以是项目、文件夹、组织和日志视图。例如，您可以定义一个日志范围，其中列出包含用于生产环境的资源的项目，或是列出包含特定资源类型的日志条目的日志视图。

创建 Trusted Cloud 项目、文件夹或组织资源时，Logging 会创建一个名为 _Default 的日志范围。此范围包含所创建的项目、文件夹或组织。如果搜索的资源是 Trusted Cloud 项目、文件夹或组织，结果会包含源自该资源，然后存储在日志存储桶中的日志条目。日志存储桶可以位于任何项目中。 搜索项目时，结果还会包含由另一个项目中的接收器路由到该项目，然后存储在日志存储桶中的日志条目。

您可以创建日志范围。您还可以修改和删除自己创建的日志范围。不过，您无法修改或删除名为 _Default 的日志范围。

您可以使用日志范围来控制 Logs Explorer 页面在哪些资源中搜索日志数据。当您打开该页面并选择某个日志范围时，该页面会搜索该范围中列出的资源，然后刷新显示内容。

对于项目，默认日志范围决定了 Logs Explorer 页面在打开时会搜索的资源集。不过，您对搜索的资源所拥有的 Identity and Access Management (IAM) 角色以及时间范围设置决定了从存储中提取哪些日志条目。创建项目时，系统会将名为 _Default 的日志范围指定为默认日志范围。

日志范围与集中式日志存储的区别

集中式日志存储和日志范围都为您提供了一种方法来查看源自不同项目的日志数据。

当您集中存储日志时，您需要在组织或文件夹中配置接收器，以将日志条目路由到单个存储位置。集中式存储提供了单一位置来查询日志数据，这在您搜索趋势或调查问题时可简化查询。从安全角度来看，您还拥有一个存储位置，这可以简化安全分析师的任务。

向日志范围中列出的资源发出查询时，系统会组合各个查询结果。日志范围有助于在读取时聚合可能存储在不同位置的日志数据。不过，日志范围还可用于提供访问权限来读取集中式日志存储桶中的一个或多个日志视图。

Logs Explorer 页面在打开时会向默认日志范围中列出的资源发出查询。因此，请配置默认范围，以便该页面显示您通常要查看的数据。例如，您可以将默认日志范围设置为列出一个日志视图，该视图在查询时会返回 App Hub 应用的日志数据。

最佳做法

由于日志范围可让您定义并保存配置以供日后使用，因此我们建议您为复杂的搜索配置创建日志范围。

例如，假设您要排查问题，并希望查看团队拥有的所有虚拟机 (VM) 实例的日志条目。如需完成此任务，您可以执行以下操作：

1. 您确定要查看的日志条目存储在多个日志存储桶和多个项目中。对于大多数日志存储桶，都存在一个包含您要分析的日志条目的日志视图。如果日志视图不存在，您可以创建一个。

2. 您决定创建日志范围，因为您预计将来会执行类似的问题排查任务。

3. 您在 Trusted Cloud 控制台中打开 Logs Explorer 页面，然后使用细化范围菜单选择新的日志范围。

4. 您查看日志条目，找到解决您正在调查的问题所需的信息。

5. 解决问题后，您与同事分享故障原因。您还分享了您预计未来会遇到类似的故障，因此您创建了一个日志范围，以便您或调查故障的任何人可快速找到相关日志条目。

App Hub 应用和日志范围

您的 App Hub 应用可能会将日志数据写入多个项目。您的日志数据可能会存储在其来源项目中，或者组织管理员可能配置了集中式存储。如需查看应用的日志数据，请创建一个日志范围，将其配置为列出存储应用日志数据的项目或日志视图，然后将其配置为默认日志范围。完成这些步骤后，Logs Explorer 页面会自动显示应用写入的数据，即使这些数据存储在不同的项目或集中式日志存储桶中时也是如此。

在您要查看日志数据的项目中创建自定义日志范围。此项目是您的 App Hub 宿主项目或已启用应用的文件夹的管理项目。例如，如果文件夹的显示名称为 My Folder，则管理项目的显示名称为 My Folder-mp。

限制

• 您无法删除或修改名为 _Default 的日志范围。
• 只有 Trusted Cloud 项目才支持默认日志范围。
• 您无法将文件夹或组织添加到用户定义的日志范围。
• 日志范围是在 global 位置创建的。

准备工作

1. In the Trusted Cloud console, on the project selector page, select or create a Trusted Cloud project.

   Go to project selector

2. Verify that billing is enabled for your Trusted Cloud project.

3. 如需获得创建和查看日志范围所需的权限，请让您的管理员为您授予项目的以下 IAM 角色：

   • Logs Configuration Writer (roles/logging.configWriter)
   • Observability Editor (roles/observability.editor)

   如需详细了解如何授予角色，请参阅管理对项目、文件夹和组织的访问权限。

   这些预定义角色具有创建和查看日志范围所需的权限。如需查看所需的确切权限，请展开所需权限部分：

   所需权限

   您需要具备以下权限才能创建和查看日志范围：

   • 设置默认日志范围： observability.scopes.{get, update}
   • 创建和管理日志范围： logging.logScopes.{create, delete, get, list, update}

   您也可以使用自定义角色或其他预定义角色来获取这些权限。

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

   gcloud

   安装 Google Cloud CLI，然后使用联合身份登录 gcloud CLI。 登录后，运行以下命令来初始化 Google Cloud CLI：

   gcloud init

   Terraform

   如需在本地开发环境中使用本页面上的 Terraform 示例，请安装并初始化 gcloud CLI，然后使用您的用户凭证设置应用默认凭证。

   1. Install the Google Cloud CLI.

   2. 配置 gcloud CLI 以使用您的联合身份。

      如需了解详情，请参阅使用联合身份登录 gcloud CLI。

   3. Create local authentication credentials for your user account:

      gcloud auth application-default login

      If an authentication error is returned, and you are using an external identity provider (IdP), confirm that you have signed in to the gcloud CLI with your federated identity.

   如需了解详情，请参阅 Trusted Cloud 身份验证文档中的为本地开发环境设置 ADC。

   REST

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

   安装 Google Cloud CLI，然后使用联合身份登录 gcloud CLI。

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

   列出日志范围

   gcloud

   如需列出项目中的日志范围，请使用 gcloud logging scopes list 命令：

    gcloud logging scopes list --project=PROJECT_ID
   

   在运行该命令之前，请更新以下字段：

   • PROJECT_ID：项目的标识符。 对于 App Hub 配置，请选择 App Hub 宿主项目或已启用应用的文件夹的管理项目。

   如需获取项目中日志范围的详细信息，请使用 gcloud logging scopes describe 命令：

    gcloud logging scopes describe LOG_SCOPE_ID --project=PROJECT_ID
   

   在运行该命令之前，请更新以下字段：

   • PROJECT_ID：项目的标识符。
   • LOG_SCOPE_ID：日志范围的 ID。例如 my-scope。

   Terraform

   您可以使用 Terraform 创建和修改日志范围。不过，您无法使用 Terraform 列出日志范围。

   REST

   Cloud Logging API 包含用于列出资源中的日志范围或报告特定日志范围详细信息的命令。如需查看完整的命令列表，请参阅 API 参考文档。

   对于 Trusted Cloud 项目，请使用以下命令：

   • projects.locations.logScopes.list。
   • projects.locations.logScopes.get。

   在上面的命令中，parent 字段具有以下语法：

   projects/PROJECT_ID/locations/LOCATION_ID
   

   上面表达式中的字段含义如下：

   • PROJECT_ID：项目的标识符。 对于 App Hub 配置，请选择 App Hub 宿主项目或已启用应用的文件夹的管理项目。
   • LOCATION_ID 必须设置为 global。

   创建日志范围

   您可以为每个项目创建 100 个日志范围。一个日志范围可包含总共 100 个日志视图和项目；但只能包含 5 个项目。您无法将文件夹或组织添加到日志范围。

   gcloud

   如需在项目中创建日志范围，请使用 gcloud logging scopes create 命令：

    gcloud logging scopes create LOG_SCOPE_ID --project=PROJECT_ID \
      --description=DESCRIPTION \
      --resource-names=RESOURCE_NAMES
   

   在运行该命令之前，请更新以下字段：

   • PROJECT_ID：项目的标识符。 对于 App Hub 配置，请选择 App Hub 宿主项目或已启用应用的文件夹的管理项目。
   • LOG_SCOPE_ID：日志范围的 ID。例如 my-scope。

   • DESCRIPTION：可选。日志范围的说明。请将说明设置为字符串格式。

   • RESOURCE_NAMES：项目或日志视图的完全限定名称的英文逗号分隔列表。例如，如需在日志范围中包含 my-project，请指定 projects/my-project。

   Terraform

   如需了解如何应用或移除 Terraform 配置，请参阅基本 Terraform 命令。 如需了解详情，请参阅 Terraform 提供程序参考文档。

   如需使用 Terraform 在项目、文件夹或组织中创建日志范围，请使用 Terraform 资源 google_logging_log_scope。

   在命令中设置以下字段：

   • parent：项目、文件夹或组织的完全限定名称。例如，您可以将此字段设置为 "projects/PROJECT_ID"，其中 PROJECT_ID 是您的 Trusted Cloud 项目的 ID。对于 App Hub 配置，请选择 App Hub 宿主项目或已启用应用的文件夹的管理项目。
   • locations：设置为 "global"。

   • name：设置为日志范围的完全限定名称。对于项目，此字段的格式为：

     "projects/PROJECT_ID/locations/global/logScopes/LOG_SCOPE_ID"
     

     在上面的表达式中，LOG_SCOPE_ID 是日志范围的名称，例如“production”。

   • resource_names：项目和日志视图的数组，其中每个项目和日志视图都使用其完全限定名称进行指定。

   • description：简要说明。例如“Scope for production resources”。

   REST

   Cloud Logging API 还支持在文件夹或组织中创建日志范围。如需了解详情，请参阅 API 参考文档。

   对于 Trusted Cloud 项目，请使用以下命令：

   • projects.locations.logScopes.create。

   在上面的命令中，parent 字段具有以下语法：

   projects/PROJECT_ID/locations/LOCATION_ID
   

   上面表达式中的字段含义如下：

   • PROJECT_ID：项目的标识符。 对于 App Hub 配置，请选择 App Hub 宿主项目或已启用应用的文件夹的管理项目。
   • LOCATION_ID 必须设置为 global。

   修改或删除日志范围

   gcloud

   如需修改项目中日志范围内的资源列表说明，请使用 gcloud logging scopes update 命令：

    gcloud logging scopes update LOG_SCOPE_ID --project=PROJECT_ID \
      --description=DESCRIPTION \
      --resource-names=RESOURCE_NAMES
   

   在运行该命令之前，请更新以下字段：

   • PROJECT_ID：项目的标识符。 对于 App Hub 配置，请选择 App Hub 宿主项目或已启用应用的文件夹的管理项目。
   • LOG_SCOPE_ID：日志范围的 ID。例如 my-scope。

   • DESCRIPTION：日志范围的说明。请将说明设置为字符串格式。如果您不想更改日志范围的说明，请省略此字段。

   • RESOURCE_NAMES：项目或日志视图的完全限定名称的英文逗号分隔列表。如果您不想更改资源列表，请省略此字段。

   如需删除项目中的日志范围，请使用 gcloud logging scopes delete 命令：

    gcloud logging scopes delete LOG_SCOPE_ID --project=PROJECT_ID
   

   在运行该命令之前，请更新以下字段：

   • PROJECT_ID：项目的标识符。 对于 App Hub 配置，请选择 App Hub 宿主项目或已启用应用的文件夹的管理项目。
   • LOG_SCOPE_ID：日志范围的 ID。例如 my-scope。

   Terraform

   如需了解如何应用或移除 Terraform 配置，请参阅基本 Terraform 命令。 如需了解详情，请参阅 Terraform 提供程序参考文档。

   如需使用 Terraform 修改项目、文件夹或组织中的日志范围，请使用 Terraform 资源 google_logging_log_scope。

   REST

   Cloud Logging API 包含可以修改或删除日志范围的命令。如需查看完整的命令列表，请参阅 API 参考文档。

   对于 Trusted Cloud 项目，请使用以下命令：

   • projects.locations.logScopes.patch。
   • projects.locations.logScopes.delete。

   在上面的命令中，parent 字段具有以下语法：

   projects/PROJECT_ID/locations/LOCATION_ID/logScopes/LOG_SCOPE_ID
   

   上面表达式中的字段含义如下：

   • PROJECT_ID：项目的标识符。 对于 App Hub 配置，请选择 App Hub 宿主项目或已启用应用的文件夹的管理项目。
   • LOCATION_ID 必须设置为 global。
   • LOG_SCOPE_ID：日志范围的 ID。例如 my-scope。

   后续步骤

   • 使用日志浏览器查看日志
   • 在日志存储桶中配置日志视图