C++ 和 OpenTelemetry

本页面适用于希望使用 OpenTelemetry 收集 C++ 应用的 Cloud Trace 数据的应用开发者。OpenTelemetry 是一个不依赖于供应商的插桩框架，可用于收集跟踪记录和指标数据。如需了解如何检测代码，请参阅插桩和可观测性。

本页面将指导您完成以下步骤：

  • 安装 OpenTelemetry 软件包。
  • 配置应用以将 span 导出到 Cloud Trace。
  • 配置您的平台。

如需了解版本信息，请参阅以下内容：

如需了解 OpenTelemetry 参考内容，请参阅以下内容：

如需了解适用于 C++ 的 OpenTelemetry 的最新详情以及其他文档和示例，请参阅 OpenTelemetry。

准备工作

启用 Cloud Trace API。

启用 API

安装 OpenTelemetry 软件包

配置将 span 导出到 Cloud Trace

如需配置轨迹数据导出，请在 main() 方法中调用 google::cloud::otel::ConfigureBasicTracing(...) 方法：

namespace gc = ::google::cloud;
[](std::string project_id) {
  auto project = gc::Project(std::move(project_id));
  auto configuration = gc::otel::ConfigureBasicTracing(project);

  MyApplicationCode();
}

project_id 字段是您要在其中存储跟踪记录的 Google Cloud 项目。

ConfigureBasicTracing(...) 方法会实例化一个实现 Cloud Trace 导出器的 TracerProvider 对象。如果调用 ConfigureBasicTracing(...) 返回的对象超出范围，则当有先前的 TracerProvider 对象存在时，系统会恢复该对象。

配置采样率

应用可能会生成大量轨迹数据。以下示例说明了如何配置采样率：

namespace gc = ::google::cloud;
[](std::string project_id) {
  auto project = gc::Project(std::move(project_id));
  auto options = gc::Options{}.set<gc::otel::BasicTracingRateOption>(.001);
  auto configuration = gc::otel::ConfigureBasicTracing(project, options);

  MyApplicationCode();
}

使用自定义 TracerProvider 导出到 Cloud Trace

您可能有需要自定义 TracerProvider 对象的用例。例如，如果要同时使用多个导出器，则需要创建自定义 TracerProvider 对象。在这些情况下，您可以直接使用 Cloud Trace 导出器：

namespace gc = ::google::cloud;
using ::opentelemetry::trace::Scope;
[](std::string project_id) {
  // Use the Cloud Trace Exporter directly.
  auto project = gc::Project(std::move(project_id));
  auto exporter = gc::otel::MakeTraceExporter(project);

  // Advanced use cases may need to create their own tracer provider, e.g. to
  // export to Cloud Trace and another backend simultaneously. In this
  // example, we just tweak some OpenTelemetry settings that google-cloud-cpp
  // does not expose.
  opentelemetry::sdk::trace::BatchSpanProcessorOptions options;
  options.schedule_delay_millis = std::chrono::milliseconds(1000);
  auto processor =
      opentelemetry::sdk::trace::BatchSpanProcessorFactory::Create(
          std::move(exporter), options);

  // Create a tracer provider and set it as the global trace provider
  opentelemetry::trace::Provider::SetTracerProvider(
      std::shared_ptr<opentelemetry::trace::TracerProvider>(
          opentelemetry::sdk::trace::TracerProviderFactory::Create(
              std::move(processor))));

  MyApplicationCode();

  // Clear the global trace provider
  opentelemetry::trace::Provider::SetTracerProvider(
      opentelemetry::nostd::shared_ptr<
          opentelemetry::trace::TracerProvider>());
}

对自己的应用进行插桩

如需了解如何配置应用以捕获跟踪记录 span，请参阅 OpenTelemetry 跟踪记录。本页面介绍了如何进行以下所有操作：

  • 创建 span
  • 创建嵌套的 Span
  • 设置 span 属性
  • 使用事件创建 span
  • 创建包含链接的 span
// For more details on the OpenTelemetry code in this sample, see:
//     https://opentelemetry.io/docs/instrumentation/cpp/manual/
namespace gc = ::google::cloud;
using ::opentelemetry::trace::Scope;
[](std::string project_id) {
  auto project = gc::Project(std::move(project_id));
  auto configuration = gc::otel::ConfigureBasicTracing(project);

  // Initialize the `Tracer`. This would typically be done once.
  auto provider = opentelemetry::trace::Provider::GetTracerProvider();
  auto tracer = provider->GetTracer("my-application");

  // If your application makes multiple client calls that are logically
  // connected, you may want to instrument your application.
  auto my_function = [tracer] {
    // Start an active span. The span is ended when the `Scope` object is
    // destroyed.
    auto scope = Scope(tracer->StartSpan("my-function-span"));

    // Any spans created by the client library will be children of
    // "my-function-span". i.e. In the distributed trace, the client calls are
    // sub-units of work of `my_function()`, and will be displayed as such in
    // Cloud Trace.
    Client client;
    client.CreateFoo();
    client.DeleteFoo();
  };

  // As an example, start a span to cover both calls to `my_function()`.
  auto scope = Scope(tracer->StartSpan("my-application-span"));
  my_function();
  my_function();
}

示例应用

如需查看示例应用，请参阅quickstart。

配置平台

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

在 Google Cloud 上运行

当您的应用在 Google Cloud 上运行时，您无需向客户端库提供服务账号形式的身份验证凭据。但是，您需要确保您的 Google Cloud 平台已启用 Cloud Trace API 访问权限范围。

如需查看受支持的 Google Cloud 环境的列表，请参阅环境支持。

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

  • App Engine 柔性环境

  • App Engine 标准环境

  • Google Kubernetes Engine (GKE)

  • Compute Engine

  • Cloud Run

如果您使用自定义访问权限范围，则必须确保启用 Cloud Trace API 访问权限范围：

  • 如需了解如何使用 Google Cloud 控制台为您的环境配置访问权限范围，请参阅配置 Google Cloud 项目。

  • 对于 gcloud 用户，请使用 --scopes 标志指定访问权限范围，并添加 trace.append Cloud Trace API 访问权限范围。例如，如需创建仅启用了 Cloud Trace API 的 GKE 集群，请执行以下操作：

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

在本地和其他位置运行

如果您的应用在 Google Cloud 之外运行，则必须向客户端库提供服务账号形式的身份验证凭据。该服务账号必须包含 Cloud Trace Agent 角色。如需查看说明，请参阅创建服务账号。

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"

查看跟踪记录

在 Google Cloud 控制台中，转到 Trace 探索器页面：

转到 Trace 探索器

您也可以使用搜索栏查找此页面。

问题排查

如需了解如何排查 Cloud Trace 的问题，请转到“问题排查”页面。

如需调试 C++ Cloud Trace 导出器，请参阅参考文档的问题排查部分。

资源