C++ 和 OpenTelemetry

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

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

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

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

如需查看 OpenTelemetry 参考内容，请参阅以下内容：

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

准备工作

启用 Cloud Trace API。

启用 API 所需的角色

如需启用 API，您需要拥有 Service Usage Admin IAM 角色 (roles/serviceusage.serviceUsageAdmin)，该角色包含 serviceusage.services.enable 权限。了解如何授予角色。

启用 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();
}

示例应用

如需查看示例应用，请参阅 快速入门。

配置您的平台

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

在运行 Google Cloud

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

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

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

如果您使用自定义访问权限范围，则必须确保已启用 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 导出器，请参阅参考文档的 问题排查部分。

资源