创建和管理跟踪记录范围

本文档介绍了如何创建和管理轨迹范围，以便轨迹探索器页面查找您要查看或分析的轨迹跨度。如果您只想查看和分析源自 Google Cloud 项目的 span，则无需配置任何跟踪范围。不过，如果您的轨迹数据存储在多个项目中（在使用微服务架构时可能会出现这种情况），那么您需要执行一些配置活动，才能查看单个 Google Cloud 项目中的所有 span。

本文档未介绍如何查看轨迹和 span。如需了解该主题，请参阅查找和探索跟踪记录。

此功能仅适用于 Google Cloud 项目。对于 App Hub 配置，请选择 App Hub 宿主项目或管理项目。

跟踪记录范围简介

跟踪记录范围是列出视图的项目级永久性资源，这些视图可用于访问您的跟踪记录数据。您可以将 Trace 探索器页面配置为按跟踪记录范围进行搜索，这意味着该页面会搜索所选范围中列出的视图。您对搜索的视图所拥有的 Identity and Access Management (IAM) 角色以及时间范围设置决定了系统从存储中提取哪些数据，然后显示这些数据。

您可以创建跟踪记录范围，还可以修改和删除自己创建的任何跟踪记录范围。如果您的服务将 span 数据写入多个 Google Cloud 项目，则需要创建跟踪记录范围。

跟踪记录范围列出的是视图，而不是 Google Cloud 项目。虽然您在配置跟踪范围时会选择项目，但系统会将这些项目的默认跟踪视图添加到该范围中。项目的默认轨迹视图对应于路径为 _Trace/Spans/_AllSpans 的视图，其中字段 _Trace、Spans 和 _AllSpans 分别是指可观测性存储桶、数据集和视图。数据集 Spans 用于存储您的轨迹数据。

除非您使用包含跟踪记录范围或跟踪记录 ID 和 span ID 的网址打开 Trace 探索器页面，否则该页面会在默认跟踪记录范围中列出的视图中搜索跟踪记录数据。创建项目时，系统会将名为 _Default 的跟踪范围设置为默认跟踪范围。不过，您可以选择其他跟踪记录范围作为默认跟踪记录范围。

可观测性范围简介

可观测性范围用于指定在打开相应的探索器页面时要使用哪些跟踪记录范围和日志范围。如果您未配置可观测性范围以列出存储数据的资源，则可能无法关联跟踪数据和日志数据。如需了解详情，请参阅为多项目查询配置可观测性范围。

App Hub 应用和轨迹范围

您的 App Hub 应用可能会将跟踪数据写入多个项目。如需获取此数据的汇总视图，请创建一个跟踪记录范围，将其配置为列出存储跟踪记录数据的所有项目的默认跟踪记录视图，然后将其配置为默认跟踪记录范围。完成这些步骤后，Trace 探索器页面会自动显示应用写入的数据，即使这些数据存储在不同的项目中也是如此。

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

准备工作

登录您的 Google Cloud 账号。如果您是 Google Cloud新手，请 创建一个账号来评估我们的产品在实际场景中的表现。新客户还可获享 $300 赠金，用于运行、测试和部署工作负载。

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

Roles required to select or create a project

• Select a project: Selecting a project doesn't require a specific IAM role—you can select any project that you've been granted a role on.
• Create a project: To create a project, you need the Project Creator role (roles/resourcemanager.projectCreator), which contains the resourcemanager.projects.create permission. Learn how to grant roles.

Note: If you don't plan to keep the resources that you create in this procedure, create a project instead of selecting an existing project. After you finish these steps, you can delete the project, removing all resources associated with the project.

Go to project selector

Verify that billing is enabled for your Google Cloud project.

Enable the Observability API.

Roles required to enable APIs

To enable APIs, you need the Service Usage Admin IAM role (roles/serviceusage.serviceUsageAdmin), which contains the serviceusage.services.enable permission. Learn how to grant roles.

Enable the API

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

Roles required to select or create a project

• Select a project: Selecting a project doesn't require a specific IAM role—you can select any project that you've been granted a role on.
• Create a project: To create a project, you need the Project Creator role (roles/resourcemanager.projectCreator), which contains the resourcemanager.projects.create permission. Learn how to grant roles.

Note: If you don't plan to keep the resources that you create in this procedure, create a project instead of selecting an existing project. After you finish these steps, you can delete the project, removing all resources associated with the project.

Go to project selector

Verify that billing is enabled for your Google Cloud project.

Enable the Observability API.

Roles required to enable APIs

To enable APIs, you need the Service Usage Admin IAM role (roles/serviceusage.serviceUsageAdmin), which contains the serviceusage.services.enable permission. Learn how to grant roles.

Enable the API

1. 如需获得创建和查看跟踪记录范围所需的权限，请让您的管理员为您授予项目的 Observability Scopes Editor (roles/observability.scopesEditor) IAM 角色。如需详细了解如何授予角色，请参阅管理对项目、文件夹和组织的访问权限。

   您也可以通过自定义角色或其他预定义角色来获取所需的权限。

   Observability Scopes Editor角色包含专用权限，可让您创建和查看跟踪记录范围。这些权限无法包含在自定义 IAM 角色中。

2. 选择标签页以了解您打算如何使用本页面上的示例：

   控制台

   当您使用 Google Cloud 控制台访问 Google Cloud 服务和 API 时，无需设置身份验证。

   gcloud

   在 Google Cloud 控制台中，激活 Cloud Shell。

   激活 Cloud Shell

   Cloud Shell 会话随即会在 Google Cloud 控制台的底部启动，并显示命令行提示符。Cloud Shell 是一个已安装 Google Cloud CLI 且已为当前项目设置值的 Shell 环境。该会话可能需要几秒钟时间来完成初始化。

   Terraform

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

   1. 安装 Google Cloud CLI。

   2. 如果您使用的是外部身份提供方 (IdP)，则必须先使用联合身份登录 gcloud CLI。

   3. 如果您使用的是本地 shell，请为您的用户账号创建本地身份验证凭证：

      gcloud auth application-default login

      如果您使用的是 Cloud Shell，则无需执行此操作。

      如果系统返回身份验证错误，并且您使用的是外部身份提供方 (IdP)，请确认您已 使用联合身份登录 gcloud CLI。

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

   REST

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

   安装 Google Cloud CLI。

   如果您使用的是外部身份提供方 (IdP)，则必须先使用联合身份登录 gcloud CLI。

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

列出跟踪记录范围

控制台

如需列出跟踪范围，请执行以下操作：

1. 在 Google Cloud 控制台中，前往 设置页面：

   前往设置

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

2. 在 Google Cloud 控制台的工具栏中，选择您的 Google Cloud 项目。对于 App Hub 配置，请选择 App Hub 宿主项目或管理项目。

3. 选择轨迹范围标签页。

   该窗口会显示您的跟踪记录范围列表。 包含“默认”图标 的条目是默认跟踪记录范围。

4. 如需查看轨迹范围的详细信息，请展开该范围。

   展开跟踪记录范围后，您可以看到该范围包含的视图列表。每行都列出了一个项目 ID 以及一个类似 _Trace/Spans/_AllSpans 的条目，用于标识跟踪记录数据的默认存储位置。字段 _Trace、Spans 和 _AllSpans 分别是指轨迹数据的可观测性存储桶、数据集和视图。_AllSpans 视图对应于存储桶中的每个条目：

   名称	说明	类型	资源
   _Default		Trace scope	1
   myscope	My description	Trace scope	2
   _Trace/Spans/_AllSpans	myproject	Trace view
   _Trace/Spans/_AllSpans	project-b	Trace view

gcloud

不受支持。

Terraform

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

REST

预览

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

如需列出 Google Cloud 项目中的所有跟踪范围，请使用 projects.locations.traceScopes.list 命令。您必须指定路径参数。

相应端点的路径参数采用以下语法：

projects/PROJECT_ID/locations/LOCATION_ID/traceScopes

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

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

响应是一个 TraceScope 对象数组。每个对象都包含一个名称和一个资源列表。

如需获取有关特定轨迹范围的信息，请使用 projects.locations.traceScopes.get 命令。

创建 trace 范围

Trace 探索器页面显示的 span 取决于搜索的视图、您在这些视图中的 IAM 角色、时间范围设置以及您应用的过滤条件。

警告： 请确保跟踪范围中列出的所有视图都将跟踪数据存储在同一位置。系统会将您的轨迹数据存储在名为 _Trace 的可观测性存储桶中。如需了解如何显示存储跟踪记录数据的位置，请参阅列出可观测性存储分区。

您可以为每个项目创建 100 个跟踪记录范围。一个跟踪记录范围最多可以包含 20 个视图。

控制台

如需创建轨迹范围，请执行以下操作：

1. 在 Google Cloud 控制台中，前往 设置页面：

   前往设置

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

2. 在 Google Cloud 控制台的工具栏中，选择您的 Google Cloud 项目。对于 App Hub 配置，请选择 App Hub 宿主项目或管理项目。
3. 选择跟踪记录范围标签页，然后点击创建跟踪记录范围。

4. 点击添加项目，然后完成对话框。

   注意： 选择项目后，系统会将该项目的默认跟踪记录视图添加到范围中。

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

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

6. 点击创建轨迹范围。

   默认情况下，跟踪范围表会以折叠形式列出您的跟踪范围。对于每个范围，该表都会列出名称、说明、类型和资源数量。

   展开跟踪记录范围后，您可以看到该范围包含的视图列表。每行都列出了一个项目 ID 以及一个类似 _Trace/Spans/_AllSpans 的条目，用于标识跟踪记录数据的默认存储位置。字段 _Trace、Spans 和 _AllSpans 分别是指轨迹数据的可观测性存储桶、数据集和视图。_AllSpans 视图对应于存储桶中的每个条目：

   名称	说明	类型	资源
   _Default		Trace scope	1
   myscope	My description	Trace scope	2
   _Trace/Spans/_AllSpans	myproject	Trace view
   _Trace/Spans/_AllSpans	project-b	Trace view

gcloud

不受支持。

Terraform

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

如需使用 Terraform 在项目中创建轨迹范围，请执行以下操作：

1. 使用 Terraform 资源 google_observability_trace_scope。

   在命令中设置以下字段：

   • project：项目、文件夹或组织的名称。例如 my-project。对于 App Hub 配置，请选择 App Hub 宿主项目或管理项目。

     注意： 选择项目后，系统会显示该项目对应数据集的 Spans 视图。_AllSpans系统会将 _AllSpans 视图添加到范围中。

   • provider：设置为 google-beta。

   • trace_scope_id：设置为范围 ID。例如 my-trace-scope。

   • location：设置为 "global"。

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

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

2. 更新 main.tf 文件后，请升级 Terraform 安装：

   terraform -init upgrade
   

   由于 google_observability_trace_scope 资源处于 Beta 版，因此必须进行升级。

REST

预览

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

如需创建轨迹范围，请使用 projects.locations.traceScopes.create 命令。您必须指定路径参数并提供 TraceScope 对象。响应是一个 TraceScope 对象。

相应端点的路径参数采用以下语法：

projects/PROJECT_ID/locations/LOCATION_ID/traceScopes

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

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

修改或删除轨迹范围

您无法删除或修改名为 _Default 的轨迹范围。您可以修改或删除所有其他轨迹范围。

控制台

如需修改或删除轨迹范围，请执行以下操作：

1. 在 Google Cloud 控制台中，前往 设置页面：

   前往设置

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

2. 在 Google Cloud 控制台的工具栏中，选择您的 Google Cloud 项目。对于 App Hub 配置，请选择 App Hub 宿主项目或管理项目。
3. 选择轨迹范围标签页。

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

   • 如需修改，请选择修改范围，然后完成对话框。
   • 如需删除，请选择删除范围，然后完成对话框。

gcloud

不受支持。

Terraform

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

如需使用 Terraform 修改项目中的轨迹范围，请执行以下操作：

1. 使用 Terraform 资源 google_observability_trace_scope。

2. 更新 main.tf 文件后，请升级 Terraform 安装：

   terraform -init upgrade
   

   由于 google_observability_trace_scope 资源处于 Beta 版，因此必须进行升级。

REST

修改范围

预览

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

如需修改轨迹范围，请使用 projects.locations.traceScopes.patch 命令。您必须指定路径参数、查询参数并提供 TraceScope 对象。查询参数用于标识更改的字段。响应是一个 TraceScope 对象。

相应端点的路径参数采用以下语法：

projects/PROJECT_ID/locations/LOCATION_ID/traceScopes/TRACE_SCOPE_NAME

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

• PROJECT_ID：项目的标识符。 对于 App Hub 配置，请选择 App Hub 宿主项目或管理项目。
• LOCATION_ID 必须设置为 global。
• TRACE_SCOPE_NAME：轨迹范围的名称。例如 my-trace-scope。

删除范围

预览

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

如需删除轨迹范围，请使用 projects.locations.traceScopes.delete 命令。您必须指定路径参数。

相应端点的路径参数采用以下语法：

projects/PROJECT_ID/locations/LOCATION_ID/traceScopes/TRACE_SCOPE_NAME

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

• PROJECT_ID：项目的标识符。 对于 App Hub 配置，请选择 App Hub 宿主项目或管理项目。
• LOCATION_ID 必须设置为 global。
• TRACE_SCOPE_NAME：轨迹范围的名称。例如 my-trace-scope。

配置默认跟踪范围

Trace 探索器页面打开时，会在默认跟踪记录范围中列出的视图中搜索跟踪记录数据。如果无法访问该跟踪记录范围，Trace 探索器页面会查询项目在默认数据集上的 _AllSpans 视图。

创建项目时，系统会创建名为 _Default 的跟踪记录范围，并将其指定为默认跟踪记录范围。不过，您可以创建自己的轨迹范围并将其指定为默认轨迹范围。

控制台

如需设置默认跟踪记录范围，请执行以下操作：

1. 在 Google Cloud 控制台中，前往 设置页面：

   前往设置

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

2. 在 Google Cloud 控制台的工具栏中，选择您的 Google Cloud 项目。对于 App Hub 配置，请选择 App Hub 宿主项目或管理项目。

3. 选择轨迹范围标签页。

   该标签页会显示您的跟踪范围，并包含用于创建自定义跟踪范围的按钮。带有“默认”图标 的跟踪记录范围是当前的默认跟踪记录范围。

4. 如需更改默认跟踪范围，请找到要指定为默认跟踪范围的跟踪范围，点击其  更多，然后选择设为默认。

   您选择的跟踪记录范围会显示带有“默认”图标 。

gcloud

不受支持。

Terraform

您可以使用 Terraform 创建和修改轨迹范围。不过，您无法使用 Terraform 设置默认跟踪记录范围。

REST

预览

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

如需使用 API 调用获取和设置默认日志范围或默认跟踪记录范围，请配置可观测性范围。可观测性范围会列出默认日志范围和默认跟踪记录范围：

• 如需获取项目的默认可观测性范围，请向 projects.locations.scopes.get 端点发送请求。您必须指定路径参数。响应是一个 Scope 对象，其中列出了默认日志范围和默认跟踪记录范围。

• 如需更新项目的默认可观测性范围，请向 projects.locations.scopes.patch 端点发送请求。您必须指定路径参数、查询参数并提供 Scope 对象。查询参数用于标识更改的字段。响应是一个 Scope 对象。

这两个端点的路径参数采用以下格式：

projects/PROJECT_ID/locations/LOCATION/scopes/OBSERVABILITY_SCOPE_ID

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

• PROJECT_ID：项目的标识符。 对于 App Hub 配置，请选择 App Hub 宿主项目或管理项目。
• LOCATION：位置字段必须设置为 global。
• OBSERVABILITY_SCOPE_ID：Scope 对象的名称。此字段必须设置为 _Default。名称为 _Default 的 Scope 对象会自动创建，用于存储有关默认日志范围和默认跟踪记录范围的信息。

如需向 API 端点发送命令，您可以使用 APIs Explorer，以便从参考页面发出命令。例如，如需获取当前默认范围，您可以执行以下操作：

1. 点击 projects.locations.scopes.get。

2. 在尝试此方法微件的名称字段中输入以下内容：

   projects/PROJECT_ID/locations/global/scopes/_Default
   

   在复制上述字段之前，请将 PROJECT_ID 替换为您的项目名称。

3. 选择执行。

4. 在授权对话框中，完成所需的步骤。

   响应类似于以下示例：

   {
   "name": "projects/my-project/locations/global/scopes/_Default",
   "logScope": "logging.googleapis.com/projects/my-project/locations/global/logScopes/_Default"
   "traceScope": "projects/my-project/locations/global/traceScopes/_Default"
   }
   

跟踪记录范围限制

跟踪记录范围限制	值
每个项目的跟踪范围数量上限	100
每个轨迹范围的视图数量上限	20

后续步骤

• 查找和探索轨迹

• Cloud Logging 和 Cloud Monitoring 包含类似的结构，可让您控制可以查看或监控的日志数据或指标数据。如需了解这些范围，请参阅以下文档：

  • 可观测性范围概览
  • 创建和管理日志范围
  • 指标范围概览