Cloud Trace 插桩

本文档概述了如何对 Cloud Trace 应用进行插桩处理。如需详细了解如何设置 Cloud Trace，请参阅特定语言的设置页面。

Cloud Trace 会为您的应用提供分布式跟踪数据。对应用进行插桩处理后，您可以检查单个请求的延迟时间数据，并在 Cloud Trace 控制台中查看整个应用的总体延迟时间。

何时对应用进行插桩处理

如果系统未自动捕获轨迹数据，您需要对您的应用进行插桩 (instrument) 处理以收集此数据。

您可以对应用进行插桩，以便其收集应用特定信息。借助多种开源插桩框架，您可以从应用中收集指标、日志和跟踪记录，并将这些数据发送到任何供应商（包括 Google Cloud）。如需对您的应用进行插桩，我们建议您使用开源的开源插桩框架（例如 OpenTelemetry），而不是特定于供应商和产品的 API 或客户端库。

如需了解如何使用与供应商无关的插桩框架来对应用进行插桩，请参阅 插桩和可观测性。

如何对应用进行插桩

如需了解有关如何对应用进行插桩以收集日志、指标和跟踪记录的建议，请参阅选择插桩方法。

如需对您的应用进行插桩 (instrument) 处理以收集轨迹数据，您可以执行以下任一操作：

何时创建 Span

Cloud Trace 客户端库通常会维护一个全局跟踪上下文，其中包含有关当前 span 的信息（包括其跟踪记录 ID 以及是否对跟踪记录进行采样）。这些库通常在 RPC 边界上创建 span。但是，如果默认创建算法不足以满足您的需求，您可能需要创建 span。

当前活跃 span 可由全局跟踪上下文访问，后者有时封装在跟踪器对象中。您可以通过对现有 span 使用自定义注释和标记来添加与应用相关的信息，也可以创建具有各自注释和标记的新子 span，从而更精细地跟踪应用的行为。由于上下文是全局性的，因此更新上下文的多线程应用必须使用适当的隔离。

何时提供身份验证凭据

在 Google Cloud 上运行时，您通常不需要向应用提供身份验证凭据或在应用中指定 Google Cloud 项目 ID。对于某些语言，即使您在 Google Cloud 上运行，也需要指定您的 Google Cloud 项目 ID。此外，如果您为 Google Kubernetes Engine 使用 Autopilot 模式，或者启用了 Workload Identity，则必须将应用配置为使用 Workload Identity。

如果您在 Google Cloud 之外运行，则需要向应用提供身份验证凭据。您还需要在应用中指定 Google Cloud 项目 ID。

有关详情，请转到特定语言的设置页面。

如何强制跟踪请求

除非您的应用始终对每个 span 进行采样，否则一般来说不可能强制对请求进行端到端跟踪，因为端到端请求中的每个组件都会做出自己的采样决策。不过，您可以通过向轨迹标头添加一个 sampled 标志并将其设置为 true 来影响该决定。此设置用于提示子组件对请求进行采样。如需详细了解跟踪记录标头，请参阅上下文传播协议。

对于您拥有代码的下游组件，您必须确定插桩逻辑是否遵循 sampled 标志。例如，使用 OpenTelemetry 进行插桩时，您可以使用 ParentBased 采样器来确保遵循父采样标志。

将跟踪信息记录到 Cloud Trace 的 Google Cloud 服务通常会接受父采样标志作为提示；但是，大多数服务也会对采样进行速率限制。每项 Google Cloud 服务都会确定其是否支持跟踪、如何使用父采样标志以及采样的速率限制。

启用 Cloud Trace API

要使用 Cloud Trace，您的 Google Cloud 项目必须启用 Cloud Trace API。此设置允许您的 Google Cloud 项目从经过身份验证的来源接收轨迹数据。默认情况下，Google Cloud 项目已启用 Cloud Trace API，您无需采取任何行动。但是，如果您修改了 Google Cloud 项目的访问权限范围，则可能需要启用 Cloud Trace API。

如需启用 Cloud Trace API，请执行以下操作：

  1. 在 Google Cloud 控制台的导航面板中，选择 API 和服务，点击启用 API 和服务，然后启用 Cloud Trace API：

    转到 Cloud Trace API 设置

  2. 如果系统显示 API 已启用，则表示此 API 已经启用。如未显示，请点击启用按钮。

后续步骤

如需详细的配置信息、示例以及指向 GitHub 和其他开源代码库的链接，请转到您所用语言的设置页面：