创建和管理轨迹范围

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

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

此功能仅适用于 Google Cloud 项目。对于 App Hub 配置，请选择 App Hub 宿主项目或已启用应用的文件夹的管理项目。

跟踪记录范围简介

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

创建 Google Cloud 项目时，系统会创建一个名为 _Default 的轨迹范围。此范围仅包括 Google Cloud 项目。您无法向此范围添加项目或删除此范围。

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

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

App Hub 应用和轨迹范围

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

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

准备工作

  1. Sign in to your Google Cloud account. If you're new to Google Cloud, create an account to evaluate how our products perform in real-world scenarios. New customers also get $300 in free credits to run, test, and deploy workloads.

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

    Go to project selector

  3. Verify that billing is enabled for your Google Cloud project.

  4. Enable the Observability API.

    Enable the API

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

    Go to project selector

  6. Verify that billing is enabled for your Google Cloud project.

  7. Enable the Observability API.

    Enable the API

    8.

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

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

    可观测性范围编辑者角色包含专用权限，可让您创建和查看轨迹范围。这些权限无法包含在自定义 IAM 角色中。

  9. 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 的凭证。

      安装 Google Cloud CLI。 安装完成后，运行以下命令来初始化 Google Cloud CLI： 

      gcloud init

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

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

    列出跟踪记录范围

    控制台

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

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

      前往设置

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

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

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

      该表会列出您的轨迹范围。选择了 Google Cloud 项目后，该表中的一个条目会显示带有“默认”图标 ，这表示它是默认跟踪记录范围。Trace 探索器页面会在打开时在默认跟踪记录范围中列出的项目中搜索跟踪记录数据。

    gcloud

    不受支持。

    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 探索器页面显示的 span 取决于搜索的项目、您在这些项目中的 IAM 角色、时间范围设置以及您应用的过滤条件。

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

    控制台

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

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

      前往设置

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

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

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

      如果您不知道要在范围中包含哪些项目，可以使用旧版跟踪记录探索器页面来帮助您确定。如需了解详情，请参阅本文档的迁移到轨迹范围部分。

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

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

    6. 点击创建轨迹范围。

    gcloud

    不受支持。

    REST

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

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

    projects/PROJECT_ID/locations/LOCATION_ID/traceScopes

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

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

    迁移到跟踪范围

    Trace 探索器页面要求您指定Google Cloud 要搜索跟踪记录数据的项目，这与旧版 Trace 探索器页面的行为有所不同。旧版 Trace 探索器页面会搜索组织中的所有项目。由于存在这些差异，Trace 探索器页面可能不会显示旧版 Trace 探索器页面显示的 span。

    您可以使用旧版 Trace 探索器页面的跟踪记录详情窗格部分，帮助您编制存储跟踪记录数据的Google Cloud 项目列表：

    1. 前往旧版 Trace 探索器页面：

      前往旧版 Trace 探索器

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

    3. 选择一个轨迹。

      您可以尝试以下操作：

      • 通过在跟踪记录 ID 字段中输入跟踪记录的 ID 来查看跟踪记录。
      • 添加过滤条件。

    4. 在跟踪记录详情窗格中，选择相应跟踪记录，然后前往项目标签页。

      此标签页列出了存储轨迹跨度的项目。

    5. 如需创建包含所列项目的轨迹范围，请前往项目标签页的工具栏，选择使用这些项目创建范围，然后完成对话框。

    6. 重复执行上述步骤，直到您整理出项目列表。

    在编制项目列表后，请创建轨迹范围。 您还可以将其设置为默认跟踪范围。

    修改或删除轨迹范围

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

    控制台

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

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

      前往设置

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

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

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

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

    gcloud

    不受支持。

    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 探索器页面打开时，会在默认跟踪记录范围中列出的项目中搜索跟踪记录数据。如果无法访问该轨迹范围，则会在您的项目中搜索轨迹数据。

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

    控制台

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

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

      前往设置

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

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

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

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

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

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

    gcloud

    不受支持。

    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

    后续步骤