C++ と OpenTelemetry

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

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

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

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

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

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

始める前に

Cloud Trace API を有効にします。

API を有効にするために必要なロール

API を有効にするには、serviceusage.services.enable 権限が必要です。プロジェクトを作成した場合は、オーナーロール（roles/owner）を介してこの権限が付与されている可能性があります。それ以外の場合は、Service Usage 管理者ロール（roles/serviceusage.serviceUsageAdmin）を介してこの権限を取得できます。ロールを付与する方法をご覧ください。

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

  • スパンを作成する
  • ネストされたスパンを作成する
  • スパン属性を設定する
  • イベントを含むスパンを作成する
  • リンクを含むスパンを作成する
// 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で実行されている場合、認証情報をサービス アカウントの形式でクライアントライブラリに提供する必要はありません。ただし、プラットフォームで Cloud Trace API のアクセス スコープ が有効になっている必要があります。 Google Cloud

サポートされている環境の一覧については、 環境サポートをご覧ください。 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）を使用して アプリケーションの認証情報を検索します。

これらの認証情報を指定するには、次の 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"

トレースを表示

コンソールで、 [ Trace エクスプローラ] ページに移動します。 Google Cloud

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

このページは、検索バーを使用して見つけることもできます。

トラブルシューティング

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

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

リソース