このドキュメントでは、OpenTelemetry SDK によるトレースデータの Google Cloud プロジェクトへのプロセス内エクスポートを構成する方法について説明します。Java、Go、Python、Node.js の例では、手動計測を使用するときにトレースデータを Telemetry(OTLP)API に送信するように SDK を構成する方法を示します。各言語について、OTLP エクスポータを使用してサポートされているエクスポート プロトコルでトレースデータを送信する方法について説明します。
このページで説明する計測は、トレースデータにのみ適用されます。ログデータや指標データは Google Cloud プロジェクトに送信されません。
アプリケーションが OpenTelemetry コレクタを使用してトレースデータを Google Cloud プロジェクトに送信している場合、このドキュメントは適用されません。
- 計測サンプルについては、コレクタベースの計測サンプルをご覧ください。
- コレクタの詳細については、Google が構築した OpenTelemetry Collector をご覧ください。
移行が必要な理由
OpenTelemetry SDK は、OpenTelemetry OTLP プロトコルで定義された proto ファイルと概ね一致する形式で、ログ、指標、トレースデータを生成します。ただし、フィールドは保存前に OpenTelemetry 固有のデータ型から JSON データ型に変換されることがあります。
アプリケーションが Google Cloud エクスポータを使用してそのデータを Google Cloud プロジェクトにエクスポートすると、エクスポータは次の手順を実行します。
- 記録されたデータを OTLP 形式から、Cloud Logging API、Cloud Monitoring API、または Cloud Trace API で定義された独自の形式に変換します。
- 変換されたデータを適切な API に送信し、 Google Cloud プロジェクトに保存します。
トレースデータの場合は、データ変換を必要としない Telemetry(OTLP)API を使用してデータをエクスポートするようにアプリケーションを移行することをおすすめします。データ変換により、一部のデータが失われる可能性があります。たとえば、独自形式では特定のフィールドの制限が低い場合や、一部の OTLP フィールドが独自形式のフィールドにマッピングされない場合があります。
利用可能なサンプル
このページで参照されているサンプル アプリケーションは GitHub で入手できます。ほとんどのアプリケーションは、gRPC を使用してトレースデータをエクスポートするように構成されています。つまり、HTTP/2 接続で gRPC ワイヤー形式を使用して protobuf エンコードされたデータを使用します。HTTP 接続を介してトレースデータを protobuf エンコードされたデータとしてエクスポートするように構成されたアプリケーションのコード例も提供されています。
-
サンプル アプリケーションは、HTTP 接続を介してトレースを protobuf エンコード データとしてエクスポートするように構成されています。gRPC を使用する場合は、このサンプルの計測が適用されます。ただし、自動構成モジュールが使用するシステム プロパティを変更する必要があります。サンプル アプリケーションは
http/protobufエクスポータを指定します。gRPC を使用するには、この設定をgrpcに変更します。サンプル アプリケーションなどの Java アプリケーションでは、OpenTelemetry SDK Autoconfigure モジュールを使用して SDK を構成することをおすすめします。
gRPC を使用する Go アプリケーションと HTTP を使用する Go アプリケーション
Go リポジトリは 2 つあります。1 つのリポジトリでは、サンプル アプリケーションは gRPC を使用します。別のリポジトリのサンプルでは、HTTP 接続で protobuf エンコード データを使用します。
-
このリポジトリには、gRPC 用と HTTP 接続で protobuf エンコード データを使用するものの 2 つのサンプルが含まれています。
-
このリポジトリには、gRPC 用と HTTP 接続で protobuf エンコード データを使用するものの 2 つのサンプルが含まれています。
始める前に
トレースデータを OTLP エンドポイントに送信するようにアプリケーションを移行する前に、Telemetry API を有効にして、必要な Identity and Access Management(IAM)ロールが付与されていることを確認します。サービス アカウントに IAM ロールを付与する必要がある場合もあります。
課金と Telemetry API を有効にする
- Sign in to your Google Cloud account. If you're new to Google Cloud, create an account to evaluate how our products perform in real-world scenarios. New customers also get $300 in free credits to run, test, and deploy workloads.
-
In the Google Cloud console, on the project selector page, select or create a Google Cloud project.
Roles required to select or create a project
- Select a project: Selecting a project doesn't require a specific IAM role—you can select any project that you've been granted a role on.
-
Create a project: To create a project, you need the Project Creator role
(
roles/resourcemanager.projectCreator), which contains theresourcemanager.projects.createpermission. Learn how to grant roles.
-
Verify that billing is enabled for your Google Cloud project.
-
Enable the Telemetry, Cloud Logging, Cloud Monitoring, and Cloud Trace APIs.
Roles required to enable APIs
To enable APIs, you need the Service Usage Admin IAM role (
roles/serviceusage.serviceUsageAdmin), which contains theserviceusage.services.enablepermission. Learn how to grant roles. -
In the Google Cloud console, on the project selector page, select or create a Google Cloud project.
Roles required to select or create a project
- Select a project: Selecting a project doesn't require a specific IAM role—you can select any project that you've been granted a role on.
-
Create a project: To create a project, you need the Project Creator role
(
roles/resourcemanager.projectCreator), which contains theresourcemanager.projects.createpermission. Learn how to grant roles.
-
Verify that billing is enabled for your Google Cloud project.
-
Enable the Telemetry, Cloud Logging, Cloud Monitoring, and Cloud Trace APIs.
Roles required to enable APIs
To enable APIs, you need the Service Usage Admin IAM role (
roles/serviceusage.serviceUsageAdmin), which contains theserviceusage.services.enablepermission. Learn how to grant roles. アプリケーションが使用するサービス アカウントに、次の IAM ロールを付与します。
- Cloud テレメトリー トレース書き込み(
roles/telemetry.tracesWriter) - ログ書き込み(
roles/logging.logWriter)| - モニタリング指標の書き込み(
roles/monitoring.metricWriter)
アプリケーションのデフォルト認証情報(ADC)については、アプリケーションのデフォルト認証情報の仕組みとローカル開発環境用のアプリケーションのデフォルト認証情報(ADC)を設定するをご覧ください。
- Cloud テレメトリー トレース書き込み(
-
ログ、指標、トレースデータを表示するために必要な権限を取得するには、プロジェクトに対する次の IAM ロールを付与するよう管理者に依頼してください。
-
ログ閲覧者(
roles/logging.viewer) -
モニタリング閲覧者(
roles/monitoring.viewer) -
Cloud トレース ユーザー(
roles/cloudtrace.user)
ロールの付与については、プロジェクト、フォルダ、組織に対するアクセス権の管理をご覧ください。
-
ログ閲覧者(
次の import ステートメントを追加します。
OpenTelemetry SDK Autoconfigure モジュールを使用して SDK を構成するようにアプリケーション コードを更新します。
自動構成モジュールが実行時に使用するシステム プロパティを構成します。このモジュールは、これらのプロパティを使用して SDK をブートストラップします。システム プロパティの代わりに環境変数を使用することもできます。詳細については、環境変数とシステム プロパティをご覧ください。
サンプル アプリケーションでは、
build.gradleスクリプトでシステム プロパティを定義しています。また、構成を JVM 引数として渡します。
gRPC を使用してトレースデータをエクスポートする場合は、OTLP プロトコルを
http/protobufに設定するのではなく、grpcに設定します。
権限を構成する
手動計測の移行ガイド
このセクションでは、Telemetry API を使用して、トレースデータを Google Cloud プロジェクトに送信するようにアプリケーションを変更する方法について説明します。このエンドポイントに指標データやログデータを送信することはできません。
依存関係を追加する
最初のステップは、アプリケーションに OpenTelemetry の OTLP トレース エクスポータの依存関係を追加することです。アプリケーションとビルドシステムに適した依存関係のバージョンを選択します。
Java
Java アプリケーションの場合は、build.gradle スクリプトに次の依存関係を追加します。
Go
このセクションでは、エクスポートに gRPC を使用する場合に依存関係に対して行う必要のある変更について説明します。エクスポートに HTTP 接続経由で protobuf エンコードされたデータを使用する場合は、otlptracehttp パッケージを依存関係として含めます。詳細については、HTTP を使用する Go アプリケーションをご覧ください。
エクスポートに gRPC を使用する Go アプリケーションの場合は、go.mod ファイルを更新して次の依存関係を含めます。
Python
このセクションでは、エクスポートに gRPC を使用する場合に依存関係に対して行う必要のある変更について説明します。エクスポートに HTTP 接続で protobuf エンコード データを使用する場合は、opentelemetry-exporter-otlp-proto-http パッケージを要件として含めます。詳細については、Python リポジトリをご覧ください。
エクスポートに gRPC を使用する Python アプリケーションの場合は、次の依存関係をインストールするか、requirements.txt ファイルを更新します。
Node.js
このセクションでは、エクスポートに gRPC を使用する場合に依存関係に対して行う必要のある変更について説明します。エクスポートに HTTP 接続経由で protobuf エンコードされたデータを使用する場合は、@opentelemetry/exporter-trace-otlp-proto パッケージを依存関係として含めます。詳細については、Node.js アプリケーションをご覧ください。
gRPC を使用してトレースデータをエクスポートする Node.js アプリケーションの場合は、次の依存関係を追加します。
"@opentelemetry/exporter-trace-otlp-grpc": "0.203.0",
"@grpc/grpc-js": "1.14.3"
Google Cloud エクスポータの使用を OTLP エクスポータに置き換える
アプリケーション コードを更新して、 Google Cloud トレース エクスポータではなく OpenTelemetry OTLP エクスポータを使用するように OpenTelemetry SDK を構成します。必要な変更は言語によって異なります。
Java
Java アプリケーションの場合は、次の操作を行います。
Go
このセクションでは、エクスポートに gRPC を使用する場合に必要な変更について説明します。エクスポートに HTTP 接続で protobuf エンコード データを使用する場合は、otlptracehttp パッケージをインポートし、対応するオプションでエクスポータを構成する必要があります。詳細については、HTTP を使用する Go アプリケーションをご覧ください。
エクスポートに gRPC を使用する Go アプリケーションの場合は、次の import ステートメントを追加します。
また、初期化コードを更新して、gRPC エクスポータで TraceProvider を構成します。
Python
このセクションでは、エクスポートに gRPC を使用する場合に必要な変更について説明します。エクスポートに HTTP 接続で protobuf エンコード データを使用する場合は、opentelemetry.exporter.otlp.proto.http パッケージからインポートし、対応するオプションでエクスポータを構成する必要があります。詳細については、Python リポジトリをご覧ください。
エクスポートに gRPC を使用する Python アプリケーションの場合は、次のインポートを追加します。
また、初期化コードを更新して、gRPC エクスポータで TraceProvider を構成します。
Node.js
このセクションでは、エクスポートに gRPC を使用する場合に必要な変更について説明します。エクスポートに HTTP 接続経由で protobuf エンコード データを使用する場合は、@opentelemetry/exporter-trace-otlp-proto パッケージをインポートします。詳細については、Node.js アプリケーションをご覧ください。
エクスポートに gRPC を使用する Node.js アプリケーションの場合は、次のインポートを追加します。
また、初期化コードを更新して、gRPC エクスポータで TraceProvider を構成します。
認証を構成する
OpenTelemetry SDK 構成に対する前回の変更により、アプリケーションは gRPC または HTTP を使用して OpenTelemetry OTLP エクスポータでトレースをエクスポートするように構成されています。次に、これらのトレースを Google Cloud プロジェクトに送信するようにエクスポータを構成する必要があります。
認証を構成するには、次の操作を行います。
このセクションでは、これらの各ステップについて詳しく説明します。
エクスポート呼び出しの認証ヘッダーを構成する
Google Cloud アプリケーションのデフォルト認証情報(ADC)を使用してエクスポータを構成するために、言語固有の Google Auth ライブラリを追加します。
Java
Trace への認証を行うには、アプリケーションのデフォルト認証情報を設定します。詳細については、ローカル開発環境の認証の設定をご覧ください。
OpenTelemetry SDK Autoconfigure モジュールを使用する Java アプリケーションの場合は、Google Cloud 認証拡張機能も使用することをおすすめします。
Go
Trace への認証を行うには、アプリケーションのデフォルト認証情報を設定します。詳細については、ローカル開発環境の認証の設定をご覧ください。
エクスポートに gRPC を使用する Go アプリケーションの場合は、go.mod ファイルを更新して次の依存関係を含めます。
エクスポートに HTTP を使用する Go アプリケーションの場合は、go.mod ファイルを更新して次の依存関係を含めます。
Python
Trace への認証を行うには、アプリケーションのデフォルト認証情報を設定します。詳細については、ローカル開発環境の認証の設定をご覧ください。
Python アプリケーションの場合は、次のインポートを追加します。
Node.js
Trace への認証を行うには、アプリケーションのデフォルト認証情報を設定します。詳細については、ローカル開発環境の認証の設定をご覧ください。
Node.js アプリケーションの場合は、次の依存関係を追加します。
"google-auth-library": "9.15.1"
次に、ライブラリから取得した認可トークンをヘッダーに追加するように OTLP スパン エクスポータを構築するアプリケーション コードを更新します。このステップは言語固有ですが、実装はすべての言語で類似しています。
Java
OpenTelemetry SDK Autoconfigure モジュールと Google Cloud 認証拡張機能を使用する Java アプリケーションがある場合、アプリケーションの初期化時に特別な手順を実行する必要はありません。自動構成モジュールは、ADC の構成に必要な手順を自動的に実行します。
Go
このセクションでは、エクスポートに gRPC を使用する場合に必要な変更について説明します。エクスポートに HTTP 接続経由で protobuf エンコードされたデータを使用する場合は、otlptracehttp パッケージをインポートし、エクスポータが otlptracehttp オブジェクトになるように構成する必要があります。詳細については、HTTP を使用する Go アプリケーションをご覧ください。
エクスポートに gRPC を使用する Go アプリケーションの場合は、次の import ステートメントを追加します。
また、初期化コードを更新して、gRPC エクスポータをインスタンス化する前に ADC を構成します。
Python
このセクションでは、エクスポートに gRPC を使用する場合に必要な変更について説明します。エクスポートに HTTP 接続で protobuf エンコード データを使用する場合は、デフォルトの認証情報を使用します。BatchSpanProcessor をインスタンス化するときに、これらの認証情報を渡す必要もあります。詳細については、Python リポジトリをご覧ください。
エクスポートに gRPC を使用する Python アプリケーションの場合は、次のインポートを追加します。
また、初期化コードを更新して、gRPC エクスポータをインスタンス化する前に ADC を構成します。
Node.js
このセクションでは、エクスポートに gRPC を使用する場合に必要な変更について説明します。エクスポートに HTTP 接続を介して protobuf エンコードされたデータを使用する場合は、ここで説明する変更とは若干異なります。詳細については、Node.js アプリケーションに含まれている app-http-proto-export.ts ファイルをご覧ください。
エクスポートに gRPC を使用する Node.js アプリケーションの場合は、次のインポートを追加します。
また、初期化コードを更新して、gRPC エクスポータをインスタンス化する前に ADC を構成します。
必要な OpenTelemetry リソース属性を構成する
プロジェクトを指定する Key-Value ペアを OTEL_RESOURCE_ATTRIBUTES 環境変数に追加します。キーには gcp.project_id を使用します。値には、 Google Cloud プロジェクトの ID を使用します。
例:
export OTEL_RESOURCE_ATTRIBUTES="gcp.project_id=PROJECT_ID"
Java を使用し、サンプル Java アプリケーションのように Google Cloud 認証拡張機能を使用するようにアプリケーションを構成する場合は、OpenTelemetry リソース属性の一部としてプロジェクト ID を設定する必要はありません。ただし、この属性を設定しても問題はありません。
OpenTelemetry 環境変数の詳細については、一般的な SDK 構成をご覧ください。
割り当てプロジェクト ID を設定する
割り当てプロジェクトは、API リクエストの使用状況を追跡する Google Cloud プロジェクトです。Telemetry API はクライアント ベースの API であるため、認証方法によって割り当てプロジェクトが自動的に識別されるかどうかが決まります。たとえば、認証にサービス アカウントを使用する場合は、割り当てプロジェクトを指定する必要はありません。ただし、認証にユーザー認証情報を使用する場合は、割り当てプロジェクトを指定する必要があります。
環境変数を使用して割り当てプロジェクトを設定できます。プログラミング言語に設定する環境変数を特定するには、環境変数を使用して割り当てプロジェクトを設定するをご覧ください。
たとえば、Go の場合は、次のように割り当てプロジェクトを設定できます。
export GOOGLE_CLOUD_QUOTA_PROJECT="QUOTA_PROJECT_ID"
認証エラーを解決する方法については、ユーザー認証情報が機能しないをご覧ください。
エクスポータ エンドポイントを構成する
OTEL_EXPORTER_OTLP_ENDPOINT 環境変数の値を Google Cloudの OTLP エンドポイントに設定します。
例:
export OTEL_EXPORTER_OTLP_ENDPOINT=https://telemetry.googleapis.com
Java と自動構成モジュールを使用している場合は、サンプル Java アプリケーションのように、システム プロパティを使用してエクスポーター エンドポイントを設定できます。この構成では、エクスポータの環境変数を設定する必要はありません。
OpenTelemetry 環境変数の詳細については、一般的な SDK 構成をご覧ください。