コレクタベースの計測サンプルの概要

テレメトリーを Google Cloudに収集して送信しながら、アプリケーション コードをベンダーに依存しない状態に保つには、Go、Java、Node.js、Python 用の OpenTelemetry コレクタベースの計測サンプルを使用します。

これらのサンプルは、指標、ログ、トレースをローカルの OpenTelemetry コレクタにエクスポートするようにインプロセス OpenTelemetry SDK を構成する方法を示しています。このコレクタは、テレメトリーを Google Cloudにルーティングします。サンプルは、Telemetry API を使用して OpenTelemetry Protocol（OTLP）形式の指標データとトレースデータを Google Cloud プロジェクトに送信し、 Google Cloud エクスポータを使用してログデータを送信します。

サンプルの仕組み

Go、Java、Node.js、Python のサンプルでは、OpenTelemetry プロトコルを使用してトレースデータと指標データを収集します。サンプルでは、構造化ログを書き込むようにロギング フレームワークを構成し、アプリケーションの stdout ストリームから読み取るように OpenTelemetry Collector を構成します。フレームワークの推奨事項については、計測方法を選択するをご覧ください。

アプリケーションは Docker を使用してビルドおよびデプロイされます。OpenTelemetry でアプリケーションを計測する場合、Docker を使用する必要はありません。

サンプルは、Cloud Shell、 Google Cloudリソース、またはローカル開発環境で実行できます。

詳細

サンプルでは、OpenTelemetry Collector をサイドカーとして使用して、アプリケーションのテレメトリーを受信して拡充し、エクスポータが Google Cloud プロジェクトに送信します。サンプル アプリケーションは、OTLP 形式をサポートする Telemetry API を使用して、指標データとトレースデータをプロジェクトに送信します。

サンプルは、次のことを示すものです。

1. OpenTelemetry Collector を使用して指標とトレースを収集するように OpenTelemetry を構成します。

   このステップの複雑さは言語によって異なります。たとえば、Go では、main 関数を更新して、テレメトリー収集を初期化し、HTTP サーバーとクライアントを構成します。

2. 構造化ログを書き込むようにロギング フレームワークを構成します。

   アプリケーションで構造化ログを書き込むことをおすすめします。これによりログペイロードが JSON オブジェクトとしてフォーマットされます。これらのログでは、特定の JSON パスを検索するクエリを作成できます。また、ログペイロード内の特定のフィールドをインデックスに登録できます。

   Google Kubernetes Engine などの一部のサービスには、構造化ログをスクレイピングして Google Cloud プロジェクトに送信するエージェントが組み込まれています。Compute Engine などの他のサービスでは、ログをスクレイピングして送信するエージェントをインストールする必要があります。インストールするエージェントについては、Ops エージェントの概要をご覧ください。

   これらのサンプルを使用するのにエージェントをインストールする必要はありません。

3. Docker ファイルを構成します。すべてのサンプルには、次の YAML ファイルが含まれています。

   • docker-compose.yaml: アプリケーションのサービス、OpenTelemetry Collector、ロードジェネレータを構成します。たとえば、OpenTelemetry Collector のサービス otelcol では、イメージ、ボリューム、環境変数を指定します。OpenTelemetry コレクタのエンドポイントは、app サービスで指定された OTEL_EXPORTER_OTLP_ENDPOINT 環境変数によって設定されます。

   • otel-collector-config.yaml: OpenTelemetry コレクタを構成します。

     • サンプルでは、指標データとトレースデータに otlp レシーバーを使用し、ログデータに filelog レシーバーを使用します。

     • サンプルでは、指標データとトレースデータに otlphttp エクスポータを使用し、ログデータに Google Cloud エクスポータを使用します。

       otlphttp エクスポータは、OTLP をサポートする Telemetry API を使用してデータをプロジェクトに送信します。 Google Cloud エクスポータは、ログデータを Cloud Logging API と互換性のある形式に変換し、変換されたデータをGoogle Cloud プロジェクトに送信します。

   • docker-compose.creds.yaml: このファイルは、必要に応じて Google Cloud認証情報ファイルを otelcol コンテナにマウントします。このファイルは、アプリケーションのデフォルト認証情報（ADC）がファイルとしてのみ使用可能なローカルマシンでサンプルを実行する場合に必要です。

必要な権限

• サンプル アプリケーションがログ、指標、トレースデータを書き込むために必要な権限を取得するには、次の IAM ロールを付与するよう管理者に依頼してください。

  • プロジェクトに対するログ書き込み （roles/logging.logWriter）
  • プロジェクトに対するモニタリング指標の書き込み （roles/monitoring.metricWriter）
  • プロジェクトに対する Cloud テレメトリー トレース書き込み （roles/telemetry.tracesWriter）
  • 割り当てプロジェクトに対する Service Usage コンシューマー （roles/serviceusage.serviceUsageConsumer）

  Cloud Shell、 Google Cloud リソース、ローカル開発環境でサンプルを実行する場合は、これらの権限で十分です。割り当てプロジェクトを構成する方法については、割り当てプロジェクトを設定するをご覧ください。

  注: 通常、本番環境アプリケーションは、ログ、指標、トレースデータの書き込みに必要な認証情報を提供するためにサービス アカウントに依存しています。このような場合は、サービス アカウントに上記のロールを付与します。

• ログ、指標、トレースデータを表示するために必要な権限を取得するには、プロジェクトに対する次の IAM ロールを付与するよう管理者に依頼してください。

  • ログビューア（roles/logging.viewer）
  • モニタリング閲覧者 （roles/monitoring.viewer）
  • Cloud トレース ユーザー（roles/cloudtrace.user）

  ロールの付与については、プロジェクト、フォルダ、組織へのアクセス権の管理をご覧ください。

  必要な権限は、カスタムロールや他の事前定義ロールから取得することもできます。

必要な API

Cloud Logging、Cloud Monitoring、Cloud Trace、Telemetry の各 API がまだ有効になっていない場合は、有効にします。

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

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

gcloud services enable logging.googleapis.com monitoring.googleapis.com cloudtrace.googleapis.com telemetry.googleapis.com

代替の計測方法

他の構成を示す他のサンプルもご覧ください。

• Trace エクスポータから OTLP エンドポイントに移行するでは、プロセス内計測を使用してトレースデータを Google Cloud プロジェクトに直接送信する方法について説明します。

  お使いの環境でコレクタの使用がサポートされている場合は、OpenTelemetry コレクタを使用してテレメトリー データをエクスポートすることをおすすめします。コレクタを使用できない場合は、データを Google Cloud プロジェクトに直接送信するプロセス内エクスポータを使用する必要があります。

• エグザンプラを使用して指標とトレースを関連付けるでは、エグザンプラを生成する Go アプリケーションを構成する方法について説明します。エグザンプラは、指標データポイントに関連付けられたサンプル データポイントです。エグザンプラを使用して、トレースデータと指標データを関連付けることができます。

• Ops エージェントと OpenTelemetry Protocol（OTLP）を使用するでは、アプリケーションから指標とトレースを収集するように Ops エージェントと OTLP レシーバーを構成する方法について説明します。

次のステップ

コレクタの詳細については、Google が構築した OpenTelemetry Collector をご覧ください。

コレクタベースのエクスポートを使用するサンプルを確認する。

• Go のサンプル
• Java のサンプル
• Node.js サンプル
• Python のサンプル