C++ と OpenTelemetry

このページは、OpenTelemetry を使用して C++ アプリケーション用の Cloud Trace データを収集するアプリケーション開発者を対象としています。OpenTelemetry は、トレースデータと指標データを収集するために使用できる、ベンダー中立型のインストルメンテーション フレームワークです。コードの計測化の詳細については、計測とオブザーバビリティをご覧ください。

このページでは、次のステップについて説明します。

• OpenTelemetry パッケージをインストールする。
• Cloud Trace にスパンをエクスポートするようにアプリケーションを構成する。
• プラットフォームを構成する。

リリース情報については、以下をご覧ください。

• C++ 用の最新ライブラリ リリース

• C++ 用 Cloud Trace エクスポータの最新リリース

OpenTelemetry リファレンス コンテンツについては、以下をご覧ください。

• Tracer
• Span

追加のドキュメントとサンプルを含め、C++ の OpenTelemetry に関する最新情報については、OpenTelemetry をご覧ください。

準備

1. Google Cloud コンソールのナビゲーション パネルで [API とサービス] を選択し、[API とサービスを有効化] をクリックして、Cloud Trace API を有効にします。

   [Cloud Trace API の設定] に移動

2. [API が有効です] が表示されている場合、API はすでに有効になっています。そうでない場合は、[有効にする] ボタンをクリックします。

OpenTelemetry パッケージをインストールする

• C++ 開発環境を設定します。
• Google Cloud C++ OpenTelemetry エクスポータ ライブラリをインストールします。インストール情報については、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();
}

注: サンプリング レートを 1.0 にすると、すべてのトレースがサンプリングされます。その結果、大量のトレースデータが生成され、使用料金が増加する可能性があります。

カスタム 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);
  auto provider = opentelemetry::sdk::trace::TracerProviderFactory::Create(
      std::move(processor));

  // Set the global trace provider
  opentelemetry::trace::Provider::SetTracerProvider(std::move(provider));

  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 Platform で Cloud Trace API のアクセス スコープが有効になっている必要があります。

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

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

• App Engine フレキシブル環境

• App Engine スタンダード環境

• Google Kubernetes Engine（GKE）

  注: Autopilot を使用している場合、または GKE クラスタで Workload Identity を有効にする場合は、Workload Identity を使用するようにアプリケーションを構成します。

• Compute Engine

• Cloud Run

カスタム アクセス スコープを使用する場合は、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 エクスプローラ] を選択します。

[Trace エクスプローラ] に移動

トラブルシューティング

Cloud Trace に関する問題のトラブルシューティングについては、トラブルシューティング ページをご覧ください。

C++ Cloud Trace エクスポータをデバッグするには、リファレンス ドキュメントのトラブルシューティングをご覧ください。

リソース

• https://opentelemetry.io/
• open-telemetry/opentelemetry-cpp GitHub リポジトリ
• google-cloud-cpp OpenTelemetry Exporters ライブラリ GitHub リポジトリ