迁移到 Observability Analytics

如果您使用接收器将跟踪记录数据导出到 BigQuery，则 本文档适用于您。我们不再建议使用接收器导出跟踪记录数据。相反，我们建议您使用 Observability Analytics，它 支持与 BigQuery 相同的 SQL 查询语言。 本文档介绍了如何从基于接收器的解决方案迁移到使用 Observability Analytics 的解决方案。它还介绍了如何使用 BigQuery 服务查询跟踪记录数据。

BigQuery 提供的服务可让您复制表或导出数据。创建关联的 BigQuery 数据集（本文档中详细介绍的可选步骤）后，您可以使用这些服务复制和导出跟踪记录数据。 如需了解详情，请参阅管理表和 数据导出简介。

如需开始使用 Observability Analytics，请参阅 查询和分析跟踪记录。

准备工作

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

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

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

4. 如需获得加载 Observability Analytics 页面、运行查询和创建关联的 BigQuery 数据集所需的权限，请让管理员向您授予项目的以下 IAM 角色：

   • Cloud Trace Admin (roles/cloudtrace.admin)
   • Observability Editor (roles/observability.editor)
   • BigQuery User (roles/bigquery.user)

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

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

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

   gcloud init

迁移到 Observability Analytics

1. 完成本文档准备工作 部分中列出的操作。这些操作包括启用 Observability 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

后续步骤

• 查询和分析跟踪记录。
• 查询示例。