Cloud Trace 插桩

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

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

何时对应用进行插桩处理

未自动捕获轨迹数据时，您需要检测 收集此类数据

你可以对应用进行插桩 应用特定信息一些开源软件 利用插桩框架，你可以收集指标、日志和 并将相应数据发送给任何供应商 包括 Google Cloud要检测您的应用，我们建议您使用 开源且独立于供应商的插桩框架，例如 OpenTelemetry（而不是 供应商和产品专用的 API 或客户端库。

有关如何使用 关于供应商中立的插桩框架，请参阅 <ph type="x-smartling-placeholder"></ph> 插桩和可观测性。

如何对应用进行插桩

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

何时创建 Span

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

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

何时提供身份验证凭据

您通常无需向 Google Cloud 控制台 或者在命令行中指定 Google Cloud 项目 ID Google Cloud 应用。对于某些语言 您需要指定自己的 Google Cloud 项目 ID Google Cloud 上运行的软件此外，如果您将 Autopilot 模式用于 Google Kubernetes Engine，或者如果启用 Workload Identity，则必须 将您的应用配置为使用 Workload Identity。

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

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

如何强制跟踪请求

除非您的应用始终对每个 span 进行采样， 通常情况下，系统无法强制对请求进行端到端跟踪 因为端到端请求中的每个组件 抽样决策。不过，您可以影响 向跟踪标头添加 sampled 标志来做出决策， 并将此标志设置为 true。此设置是对子组件的提示 对请求进行采样。 如需详细了解跟踪记录标头，请参阅 上下文传播协议。

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

将跟踪信息记录到 Cloud Trace 的 Google Cloud 服务 通常接受父级抽样标志作为提示；不过，大多数 服务还会限制抽样率每项 Google Cloud 服务 确定是否支持跟踪、父采样如何 标志以及抽样速率限制。

如何将指标数据与跟踪记录数据相关联

您可以将分布值指标数据关联起来 通过向指标数据点附加样本来进行跟踪记录。 如果您已完成必要的配置步骤 OpenTelemetry 是推荐的插桩库 会自动添加这些范例如需了解详情，请参阅 使用示例关联指标和跟踪记录。

配置项目和平台

  1. 确保已启用 Cloud Trace API。

    默认情况下，Google Cloud 项目已启用 Cloud Trace API，因此您无需执行任何操作。然而，定义的安全约束 可能已经停用了该 API。问题排查 请参阅 在受限的 Google Cloud 环境中开发应用。

    启用 Cloud Trace API。

    启用 API

  2. 配置您的平台。

    您可以在 Google Cloud 和其他平台上使用 Cloud Trace。

    • Google Cloud：当您的应用在 Google Cloud，您无需提供身份验证凭据 以服务账号的形式提供给客户端库。但是， 请确保您的 Google Cloud 平台 Cloud Trace API 访问权限范围 。

      对于以下配置，默认的访问权限范围设置 包括 Cloud Trace API 访问权限范围：

      如果您使用自定义访问权限范围，则必须确保 Cloud Trace API 访问权限范围已启用。 例如，如果您使用 Google Cloud CLI 创建 GKE 集群，如果您指定 --scopes 标志， 然后确保范围包含 trace.append。以下命令 展示了如何设置 --scopes 标志：

      gcloud container clusters create example-cluster-name --scopes=https://www.googleapis.com/auth/trace.append

    • 在本地和其他位置运行：如果您的应用在 Google Cloud，则必须在 Google Cloud 中提供身份验证凭据， 以服务账号的形式访问客户端库。 必须为服务账号授予 Cloud Trace 代理 (roles/cloudtrace.agent) 角色。有关角色的信息，请参阅 使用 IAM 控制访问权限。

      Google Cloud 客户端库会使用应用默认凭据 (ADC) 查找应用的凭据。您可以通过以下其中一种渠道提供这些凭据： 三种方法：

      • 运行 gcloud auth application-default login

      • 将服务账号放在操作系统的默认路径中。 下面列出了 Windows 和 Linux 的默认路径：

        • Windows：%APPDATA%/gcloud/application_default_credentials.json

        • Linux：$HOME/.config/gcloud/application_default_credentials.json

      • 将 GOOGLE_APPLICATION_CREDENTIALS 环境变量设置为 您的服务账号的路径：

        Linux/macOS

          export GOOGLE_APPLICATION_CREDENTIALS=path-to-your-service-accounts-private-key

        Windows

          set GOOGLE_APPLICATION_CREDENTIALS=path-to-your-service-accounts-private-key

        PowerShell：

          $env:GOOGLE_APPLICATION_CREDENTIALS="path-to-your-service-accounts-private-key"

后续步骤

如需了解详细的配置信息、示例以及指向 GitHub 和 请前往您所用语言的设置页面。