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 トレースをご覧ください。このページでは、次のすべてを行う方法について説明します。

  • スパンを作成する
  • ネストされたスパンを作成する
  • スパン属性を設定する
  • イベントを使用してスパンを作成する
  • リンクを含むスパンを作成する
// 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();
}

サンプル アプリケーション

サンプル アプリケーションについては、クイックスタートをご覧ください。

プラットフォームの構成

Cloud Trace は Google Cloud と他のプラットフォームで使用できます。

Google Cloudで実行中

アプリケーションが Google Cloudで実行されている場合、認証情報をサービス アカウントの形式でクライアント ライブラリに提供する必要はありません。ただし、 Google Cloud プラットフォームで Cloud Trace API のアクセス スコープが有効になっている必要があります。

サポートされている環境の一覧については、環境のサポートをご覧ください。 Google Cloud

次の構成では、デフォルトのアクセス スコープ設定により Cloud Trace API が有効化されます。

カスタム アクセス スコープを使用する場合は、Cloud Trace API のアクセス スコープを有効にする必要があります。

  • Google Cloud Console を使用して環境のアクセス スコープを構成する方法については、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）を使用してアプリケーションの認証情報を検索します。

これらの認証情報を指定するには、次の 3 つの方法があります。

  • 実行 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 エクスポータをデバッグするには、リファレンス ドキュメントのトラブルシューティング セクションをご覧ください。

リソース