このページでは、次のステップについて説明します。
- OpenTelemetry パッケージをインストールする。
- Cloud Trace にスパンをエクスポートするようにアプリケーションを構成する。
- プラットフォームを構成する。
リリース情報については、以下をご覧ください。
OpenTelemetry リファレンス コンテンツについては、以下をご覧ください。
追加のドキュメントとサンプルを含め、Go の OpenTelemetry に関する最新情報については、OpenTelemetry をご覧ください。
準備
-
Google Cloud コンソールのナビゲーション パネルで [API とサービス] を選択し、[API とサービスを有効化] をクリックして、Cloud Trace API を有効にします。
[API が有効です] が表示されている場合、API はすでに有効になっています。そうでない場合は、[有効にする] ボタンをクリックします。
クライアントのインストール、初期化、使用
Compute Engine と Google Kubernetes Engine で Go アプリケーションを計測するには、次の手順をご覧ください。OpenTelemetry を使用する一般的な例については、Go 用の OpenTelemetry GitHub リポジトリをご覧ください。
Compute Engine
OpenTelemetry パッケージをインストールします。
go get go.opentelemetry.io/otel
go get github.com/GoogleCloudPlatform/opentelemetry-operations-go/exporter/trace
OpenTelemetric と Cloud Trace のエクスポート パッケージをインポートします。
エクスポータとトレース プロバイダを作成します。
エクスポータを作成するときは、Google Cloud プロジェクト ID に関する情報を指定します。この例では、ID が環境変数 GOOGLE_CLOUD_PROJECT
に格納されます。
サンプル アプリケーションは、WithBatcher
関数を呼び出して、トレース プロバイダがバックグラウンド プロセスを使用して Cloud Monitoring にスパンを送信するように構成します。このサンプルは、アプリの終了時にエクスポータの Shutdown
関数を呼び出すように構成されています。Shutdown
が実行されると、保留中のすべてのスパンが Cloud Monitoring に送信されます。サンプルに示されている構成は、コンテナをいつでもシャットダウンできる Cloud Run を含め、すべての運用環境で推奨される実施例です。
Tracer
インスタンスを作成するときは、名前を指定します。この例では、名前は example.com/trace
です。この方法では、複数のインスタンスを持つことができるので、これらのインスタンスにはトレースするコンポーネントの名前を付けることをお勧めします。
このサンプルが実行されると、foo
という名前の単一のトレースが作成されます。
GKE
Dockerfile
に次の行を追加します。
RUN go get go.opentelemetry.io/otel
RUN go get github.com/GoogleCloudPlatform/opentelemetry-operations-go/exporter/trace
OpenTelemetric と Cloud Trace のエクスポート パッケージをインポートします。
エクスポータとトレース プロバイダを作成します。
エクスポータを作成するときは、Google Cloud プロジェクト ID に関する情報を指定します。この例では、ID が環境変数 GOOGLE_CLOUD_PROJECT
に格納されます。
サンプル アプリケーションは、WithBatcher
関数を呼び出して、トレース プロバイダがバックグラウンド プロセスを使用して Cloud Monitoring にスパンを送信するように構成します。このサンプルは、アプリの終了時にエクスポータの Shutdown
関数を呼び出すように構成されています。Shutdown
が実行されると、保留中のすべてのスパンが Cloud Monitoring に送信されます。サンプルに示されている構成は、コンテナをいつでもシャットダウンできる Cloud Run を含め、すべての運用環境で推奨される実施例です。
Tracer
インスタンスを作成するときは、名前を指定します。この例では、名前は example.com/trace
です。この方法では、複数のインスタンスを持つことができるので、これらのインスタンスにはトレースするコンポーネントの名前を付けることをお勧めします。
このサンプルが実行されると、foo
という名前の単一のトレースが作成されます。
カスタムスパンの作成方法
カスタムスパンを作成することで、システムが作成したトレースに別の情報を追加できます。
foo
という名前のカスタムスパンを作成するには、次のコードをソースコードに追加します。
ここで、example.com/trace
はトレーサー インスタンスの名前です。
プラットフォームの構成
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)
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 エクスプローラ] を選択します。
トラブルシューティング
Cloud Trace に関する問題のトラブルシューティングについては、トラブルシューティング ページをご覧ください。