创建和管理日志作用域

预览

本产品或功能须遵守服务专用条款的“通用服务条款”部分中的“非正式版产品条款”。 正式发布前产品和功能“按原样”提供，可能仅提供有限支持。 如需了解详情，请参阅发布阶段说明。

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

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

日志范围简介

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

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

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

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

您还可以使用日志范围来控制日志面板搜索日志数据的资源。日志面板是一种用于显示日志数据的自定义信息中心微件。每个日志面板都有自己的配置，这样您就可以创建包含多个日志面板的信息中心，每个面板显示不同的日志数据。如需了解详情，请参阅在自定义信息中心内显示日志和错误。

对于项目，默认日志范围决定了日志浏览器页面打开时会搜索的一组资源。不过，您在搜索的资源上的 Identity and Access Management (IAM) 角色和时间范围设置决定了系统会从存储空间提取哪些日志条目。创建项目时，系统会将名为 _Default 的日志范围指定为默认日志范围。您可以设置哪些日志范围是默认日志范围。

最佳做法

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

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

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

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

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

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

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

限制

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

准备工作

• 如需获得创建和查看日志范围以及设置默认日志范围所需的权限，请让您的管理员为您授予以下 IAM 角色：

  • 如需创建和查看日志范围或获取默认日志范围：针对您的项目、文件夹或组织的 Logs Configuration Writer (roles/logging.configWriter)
  • 如需设置默认日志范围：针对您的项目、文件夹或组织的 Observability Editor (roles/observability.editor)

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

  这些预定义角色包含创建和查看日志范围以及设置默认日志范围所需的权限。如需查看所需的确切权限，请展开所需权限部分：

  所需权限

  如需创建和查看日志范围以及设置默认日志范围，需要具备以下权限：

  • 如需获取和设置默认日志范围： observability.scopes.{get, update}

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

• 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.

  Terraform

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

  1. Install the Google Cloud CLI.

  2. To initialize the gcloud CLI, run the following command:

     gcloud init

  3. If you're using a local shell, then create local authentication credentials for your user account:

     gcloud auth application-default login

     You don't need to do this if you're using Cloud Shell.

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

  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 控制台中，转到 设置页面：

   前往设置

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

2. 选择日志范围标签页。

   表格中列出了您的日志作用域。选择 Google Cloud 项目后，表格中会显示一个带有“默认”图标 的条目，表示此日志范围会列出 Logs Explorer 打开该页面时会搜索的资源。

gcloud

注意 ：本页中的 Google Cloud CLI 命令已配置为查询 Google Cloud 项目。如需查询文件夹，请将 --project 字段替换为 --folder 字段。同样，如需查询组织，请将 --project 字段替换为 --organization 字段。

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

 gcloud logging scopes list --project=PROJECT_ID

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

• PROJECT_ID：项目的标识符。

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

 gcloud logging scopes describe LOG_SCOPE --project=PROJECT_ID

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

• PROJECT_ID：项目的标识符。
• LOG_SCOPE：日志范围的名称。 例如 my-scope。

Terraform

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

REST

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

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

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

在 API 命令中，将 locations 字段设置为 global。

设置默认日志范围

默认日志范围会列出 Logs Explorer 页面打开时会搜索的资源。如果默认日志范围不存在或无法访问，该页面会自动搜索源自所选项目、文件夹或组织的日志条目。日志浏览器页面显示的日志条目取决于搜索的资源、时间范围设置以及您在搜索的资源上的 IAM 角色。

创建项目时，系统会创建一个名为 _Default 的日志范围，并将其指定为默认日志范围。不过，您可以创建自己的日志范围并将其指定为默认日志范围。

控制台

如需设置默认日志范围，请执行以下操作：

1. 在 Google Cloud 控制台中，转到 设置页面：

   前往设置

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

2. 选择日志范围标签页。

3. 找到要指定为默认日志范围的日志范围，点击  More（更多），然后选择 Set as default（设为默认）。

   您选择的日志范围会显示“默认”图标 。

gcloud

不受支持。

Terraform

您可以使用 Terraform 创建和修改日志范围。不过，您无法使用 Terraform 设置默认日志范围。

REST

不受支持。

创建日志范围

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

控制台

如需创建日志范围，请执行以下操作：

1. 在 Google Cloud 控制台中，转到 设置页面：

   前往设置

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

2. 选择日志范围标签页，然后点击创建日志范围。

3. 如需添加一个或多个项目，请点击添加项目，然后完成对话框。

   添加项目后，您可以查看哪些日志条目取决于您在该项目中的 IAM 角色。例如，您的 IAM 角色可能只允许您查看日志存储桶中特定日志视图可访问的日志条目。如需详细了解角色，请参阅记录角色。

4. 如需添加一个或多个日志视图，请点击添加日志视图，然后完成对话框。

   该对话框会列出包含源自当前项目或由其他项目中的接收器路由到当前项目的日志条目的所有日志视图。例如，如果您尚未配置任何接收器，则此对话框会列出当前项目中的日志视图。

   如需列出存储在其他 Google Cloud 项目中的日志视图，请点击  Import project（导入项目），然后选择相应的 Google Cloud 项目。

   添加日志视图后，您在日志视图或存储日志视图的项目中的 IAM 角色将决定您可以访问哪些日志条目。如需了解详情，请参阅控制对日志视图的访问权限。

5. 在为日志范围命名部分，输入您希望在日志范围标签页上显示的名称和说明。

   日志范围的名称无法修改，并且在项目中必须唯一。

6. 点击创建日志范围。

gcloud

注意 ：本页中的 Google Cloud CLI 命令已配置为查询 Google Cloud 项目。如需查询文件夹，请将 --project 字段替换为 --folder 字段。同样，如需查询组织，请将 --project 字段替换为 --organization 字段。

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

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

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

• PROJECT_ID：项目的标识符。

• LOG_SCOPE：日志范围的名称。 例如 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 是您的 Google Cloud 项目的 ID。
• locations：设置为 "global"。

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

  "projects/PROJECT_ID/locations/global/logScopes/LOG_SCOPE"
  

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

• resource_names：一个项目和日志视图数组，其中每个项目和日志视图均通过其完全限定名称指定。

• description：简要说明。例如，“生产资源的范围”。

REST

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

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

• projects.locations.logScopes.create。

在 API 命令中，将 locations 字段设置为 global。

修改或删除日志范围

控制台

如需修改或删除您或同事创建的日志范围，请执行以下操作：

1. 在 Google Cloud 控制台中，转到 设置页面：

   前往设置

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

2. 选择日志范围标签页。

3. 找到您要修改或删除的日志范围，点击  更多，然后执行以下操作之一：

   • 如需修改，请选择修改范围，然后在对话框中填写信息。
   • 如要删除，请选择删除镜重，然后在对话框中填写信息。

gcloud

注意 ：本页中的 Google Cloud CLI 命令已配置为查询 Google Cloud 项目。如需查询文件夹，请将 --project 字段替换为 --folder 字段。同样，如需查询组织，请将 --project 字段替换为 --organization 字段。

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

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

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

• PROJECT_ID：项目的标识符。

• LOG_SCOPE：日志范围的名称。 例如 my-scope。

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

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

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

 gcloud logging scopes delete LOG_SCOPE --project=PROJECT_ID

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

• PROJECT_ID：项目的标识符。
• LOG_SCOPE：日志范围的名称。 例如 my-scope。

Terraform

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

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

REST

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

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

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

在 API 命令中，将 locations 字段设置为 global。

后续步骤

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