C++ 和 OpenTelemetry

本頁面適用於想使用 OpenTelemetry 收集 C++ 應用程式 Cloud Trace 資料的應用程式開發人員。OpenTelemetry 是供應商中立的檢測架構,可用於收集追蹤記錄和指標資料。如要瞭解如何檢測程式碼,請參閱「檢測和可觀察性」。

本頁面會引導您完成下列步驟:

  • 安裝 OpenTelemetry 套件。
  • 設定應用程式,將跨度匯出至 Cloud Trace。
  • 設定平台。

如需發布資訊,請參閱下列資源:

如需 OpenTelemetry 參考內容,請參閱以下資源:

如需 C++ 適用的 OpenTelemetry 最新詳細資料、相關說明文件和範例,請參閱 OpenTelemetry

事前準備

Enable the Cloud Trace API.

Enable the API

安裝 OpenTelemetry 套件

設定匯出跨距至 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>());
}

檢測您自己的應用程式

如要瞭解如何設定應用程式以擷取追蹤記錄跨距,請參閱「OpenTelemetry 追蹤記錄」。本頁面將說明如何執行下列所有操作:

  • 建立 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 代理人角色。如需操作說明,請參閱「建立服務帳戶」。

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 Explorer」頁面:

前往「Trace Explorer」頁面

您也可以透過搜尋列找到這個頁面。

疑難排解

如要瞭解如何排解 Cloud Trace 問題,請前往疑難排解頁面

如要對 C++ Cloud Trace 匯出器進行偵錯,請參閱參考說明文件的「疑難排解」一節。

資源