迁移到 Observability Analytics

如果您使用跟踪记录接收器将 Cloud Trace 数据导出到 BigQuery，请迁移到 Observability Analytics。轨迹接收器已弃用，将于 2027 年 2 月 18 日当天或之后移除。 借助 Observability Analytics，您可以使用与 BigQuery 相同的 SQL 查询语言直接查询跟踪记录数据，而无需管理导出接收器。

如果您想使用 BigQuery 服务来联接数据集、管理表或导出数据，则可以创建关联的 BigQuery 数据集。您可以在迁移时或稍后创建关联的 BigQuery 数据集。如需开始使用 Observability Analytics，请参阅查询和分析轨迹。

准备工作

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

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

    Go to project selector

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

  4. Enable the Observability API, if it is not already enabled.

    Roles required to enable APIs

    To enable APIs, you need the serviceusage.services.enable permission. If you created the project, then you likely already have this permission through the Owner role (roles/owner). Otherwise, you can get this permission through the Service Usage Admin role (roles/serviceusage.serviceUsageAdmin). Learn how to grant roles.

    Enable the API

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

    Go to project selector

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

  7. Enable the Observability API, if it is not already enabled.

    Roles required to enable APIs

    To enable APIs, you need the serviceusage.services.enable permission. If you created the project, then you likely already have this permission through the Owner role (roles/owner). Otherwise, you can get this permission through the Service Usage Admin role (roles/serviceusage.serviceUsageAdmin). Learn how to grant roles.

    Enable the API

    8.

  8. 如需获得加载可观测性分析页面、运行查询和创建关联的 BigQuery 数据集所需的权限，请让管理员为您授予项目的以下 IAM 角色：

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

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

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

    激活 Cloud Shell

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

迁移到 Observability Analytics

  1. 完成本文档准备工作部分中列出的操作。这些操作包括启用可观测性 API。

  2. 使用 Observability Analytics 验证您是否有权访问跟踪记录数据：

    1. 在 Google Cloud 控制台中，前往 Observability Analytics 页面：

      前往 Observability Analytics

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

    2. 在视图菜单中，前往 跟踪记录部分，然后选择 _Trace.Spans._AllSpans。

      架构窗格会更新并显示架构。

      如果您没有看到名为 _Trace.Spans._AllSpans 的视图，则表示您的Google Cloud 项目不包含名为 _Trace 的可观测性存储桶。如需了解如何解决此情况，请参阅跟踪存储初始化失败。

    3. 在架构窗格中，选择查询。

      查询编辑器字段会更新。FROM 子句列出了类似于以下内容的条目：

      `PROJECT_ID.us._Trace.Spans._AllSpans`

    4. 在工具栏中，选择运行查询。

      如果工具栏显示在 BigQuery 上运行，请点击 设置，然后选择 Analytics（默认）。

    您已验证可以使用 Observability Analytics 页面查询轨迹数据。

  3. 可选：如果您想将跟踪记录数据与可供 BigQuery 使用的其他商家数据联接，请创建关联的 BigQuery 数据集。如需了解详情，请参阅查询关联的 BigQuery 数据集。

  4. 删除轨迹接收器和不必要的数据集：

    1. 如需列出现有跟踪接收器，请执行 gcloud alpha trace sinks list 命令：

      gcloud alpha trace sinks list

    2. 针对每个接收器，执行 gcloud alpha trace sinks delete 命令：

      gcloud alpha trace sinks delete SINK_NAME

    3. 可选：删除所有不必要的 BigQuery 数据集。 如需了解如何删除 BigQuery 数据集，请参阅删除数据集。

架构比较

本部分介绍了 Observability Analytics 与基于接收器的导出架构之间的区别。

名称 分析 旧版
跟踪记录 ID trace_id extendedFields.traceId
span ID span_id span.spanId
父级 span ID parent_span_id span.parentSpanId
Span 名称 name span.displayName.value
Span 种类 kind
如需了解值，请参阅 OpenTelemetry：SpanKind。 		span.spanKind
如需了解值，请参阅 Cloud Trace API 参考文档 SpanKind 页面。
Span 开始时间 start_time span.startTime
Span 结束时间 end_time span.endTime
属性

span、资源和检测属性各自具有独特的格式。这些字段具有 BigQuery JSON 数据类型。 示例：

  • attributes["somekey"]
  • resource.attributes["somekey"]
  • instrumentation_scope.attributes["somekey"]

所有属性均采用相同的格式： span.attributes.attributeMap.ATTRIBUTE_KEY

示例：

  • span.attributes.attributeMap._http_method
  • span.attributes.attributeMap.g_co_agent
  • span.attributes.attributeMap.rpc_service
  • span.attributes.attributeMap.rpc_method

后续步骤