Ops エージェントと OpenTelemetry Protocol（OTLP）を使用する

このドキュメントでは、Ops エージェントと OpenTelemetry Protocol（OTLP）レシーバーを使用し、OpenTelemetry で計測され Compute Engine で実行されているアプリケーションからユーザー定義の指標とトレースを収集する方法について説明します。

このドキュメントの構成は次のとおりです。

• 概要。OTLP レシーバーのユースケースについて説明します。
• 前提条件。OTLP レシーバーを使用するための前提条件について説明します。
• OTLP レシーバーを使用するエージェントの構成
• レシーバーを使用した指標の収集。このセクションでは、Cloud Monitoring で OpenTelemetry 指標をクエリする方法について説明します。
• レシーバーを使用したトレースの収集。このセクションでは、サービス アカウントに Cloud Trace への書き込みを許可する方法について説明します。

OTLP レシーバーの使用の概要

Ops エージェントの OTLP レシーバーを使用すると、次のことができます。

• OpenTelemetry 用の言語別 SDK のいずれかを使用して、アプリケーションを計測可能にする。サポートされている言語については、OpenTelemetry による計測をご覧ください。OpenTelemetry SDK と Ops エージェントを組み合わせると、次の処理が自動的に行われます。
  • アプリケーションから OTLP 指標を収集し、分析のために Cloud Monitoring に送信する。
  • アプリケーションから OTLP スパン（トレースデータ）を収集し、分析のために Cloud Trace に送信する。
• OTLP のサポートが組み込まれたサードパーティ アプリや、そのようなサポートを備えたプラグイン（Nginx など）からトレースを収集する。Ops エージェントの OTLP レシーバーはこれらのトレースを収集できます。例については、OpenTelemetry nginx モジュールをご覧ください。
• OpenTelemetry カスタム計測を使用する。
• OpenTelemetry 自動計測を使用する。

レシーバーを使用すると、指標、トレース、またはその両方を収集できます。Ops エージェントが指標を収集したら、グラフ、ダッシュボード、アラート ポリシーなど、Cloud Monitoring の機能を使用して指標をモニタリングできます。アプリケーションがトレースデータも送信する場合は、Cloud Trace を使用してデータを分析できます。

利点

Ops エージェントの OTLP プラグインが使用できるようになる前は、ユーザー定義の指標とトレースを収集するためにアプリケーションを計測可能にする主な方法として次の手段がありました。

• Monitoring API または Trace API を実装するクライアント ライブラリを使用する。
• 古い OpenCensus ライブラリを使用する。

OpenTelemetry と OTLP レシーバーを使用すると、次のような利点があります。

• OpenTelemetry は OpenCensus に代わるものです。OpenCensus プロジェクトはアーカイブ化されます。詳細については、OpenTelemetry とはをご覧ください。
• 取り込みはエージェント レベルで制御されるため、エージェントの構成が変更された場合にアプリケーションを再デプロイする必要はありません。
• アプリケーションで Google Cloud の認証情報を設定する必要はありません。すべての認証はエージェント レベルで処理されます。
• アプリケーション コードに Google Cloud 固有のモニタリング コードやトレースコードが含まれていません。Monitoring API や Trace API を直接使用する必要はありません。
• アプリケーションは Ops エージェントにデータを push します。アプリケーションがクラッシュした場合でも、Ops エージェントが収集したデータは失われません。

制限事項

Ops エージェント レシーバーによって公開される OTLP リスナーは、gRPC トランスポートをサポートしています。主に JavaScript クライアントに使用されている HTTP はサポートしていません。OpenTelemetry プロトコルの詳細については、プロトコルの詳細をご覧ください。

OTLP レシーバーはログを収集しません。ログは、Ops エージェントやその他のレシーバーを使用して収集でき、ログ情報を OTLP スパンに含めることができますが、OTLP レシーバーはログの直接収集をサポートしていません。Ops エージェントを使用してログを収集する方法については、ロギング構成をご覧ください。

前提条件

OTLP レシーバーと Ops エージェントを使用して OTLP 指標とトレースを収集するには、バージョン 2.37.0 以降の Ops エージェントをインストールする必要があります。

このドキュメントは、OpenTelemetry SDK のいずれかを使用して作成された OpenTelemetry ベースのアプリケーションがすでにあることを前提としています。このドキュメントでは、OpenTelemetry SDK の使用方法については説明しません。SDK とサポートされている言語については、OpenTelemetry による計測化をご覧ください。

Ops エージェントを構成する

OTLP レシーバーを使用するように Ops エージェントを構成するには、次の操作を行います。

1. Ops エージェントのユーザー構成ファイルを変更して OTLP レシーバーを含めます。
2. Ops エージェントを再起動します。

以降のセクションでは、各ステップについて説明します。

Ops エージェントのユーザー構成ファイルを変更する

OTLP レシーバーの構成要素を Ops エージェントのユーザー構成ファイルに追加します。

• Linux の場合: /etc/google-cloud-ops-agent/config.yaml
• Windows の場合: C:\Program Files\Google\Cloud Operations\Ops Agent\config\config.yaml

エージェントの構成に関する一般的な情報については、構成モデルをご覧ください。

OTLP レシーバーには、Ops エージェントの combined 構成セクションがあります。レシーバーを使用するには、指標とトレースの両方を使用していない場合でも、それぞれのサービスを構成する必要があります。

以下のセクションでは、OTLP レシーバーの構成手順について説明します。

combined レシーバー セクションを追加する

OTLP 指標とトレースのレシーバーを combined セクションに追加します。combined セクションではプロセッサやサービスを使用することはできません。combined セクションでレシーバーと同じ名前のレシーバーを構成しないでください。次の例では、レシーバーの名前として otlp を使用しています。

OTLP の最小 combined 構成は次のようになります。

combined:
  receivers:
    otlp:
      type: otlp

otlp レシーバーには、次の構成オプションがあります。

• type: 必須。必ず otlp にします。
• grpc_endpoint: 省略可。OTLP レシーバーがリッスンする gRPC エンドポイント。デフォルトは 0.0.0.0:4317 です。

• metrics_mode: 省略可。デフォルトは googlemanagedprometheus です。つまり、レシーバーは Managed Service for Prometheus でも使用される Prometheus API を使用して、Prometheus 形式の指標として OTLP 指標を送信します。

  Monitoring API を使用して指標を Cloud Monitoring のカスタム指標として送信するには、metrics_mode オプションを値 googlecloudmonitoring に設定します。

  この選択は、指標の取り込み方法と請求に関する測定方法に影響します。指標形式の詳細については、OTLP 指標の取り込み形式をご覧ください。

サービスに OTLP パイプラインを追加する

OTLP レシーバーは指標とトレースを収集できるため、指標とトレースのサービスを定義する必要があります。指標もトレースも収集しない場合は、空のサービスを作成します。すでに他のパイプラインを持つサービスがある場合は、それらのサービスに OTLP パイプラインを追加できます。

次の例は、パイプラインに OTLP レシーバーが含まれている metrics サービスと traces サービスを示しています。

combined:
  receivers:
    otlp:
      type: otlp
metrics:
  service:
    pipelines:
      otlp:
        receivers: [otlp]
traces:
  service:
    pipelines:
      otlp:
        receivers: [otlp]

OTLP 収集に metrics や traces サービスを使用しない場合は、OTLP レシーバーをサービスのパイプラインから除外します。パイプラインがない場合でも、サービスは存在していなければなりません。アプリケーションが特定のタイプのデータを送信し、レシーバーを含む対応するパイプラインがない場合、Ops エージェントはデータを破棄します。

Ops エージェントを再起動する

構成の変更を適用するには、Ops エージェントを再起動する必要があります。

OTLP 指標を収集する

OTLP レシーバーを使用して OpenTelemetry アプリケーションから指標を収集する場合、レシーバー構成の主な選択肢は指標の取り込みに使用する API になります。

選択するには、otlp レシーバーの構成で metrics_mode オプションを変更するか、デフォルト値を使用します。この選択は、OTLP 指標がどのように Cloud Monitoring に取り込まれるかと、請求の際にそのデータがどのように測定されるかに影響します。

metrics_mode の選択は、Monitoring でのグラフ、ダッシュボード、アラート ポリシーの作成機能には影響しません。

• グラフとダッシュボードの作成については、ダッシュボードとグラフの概要をご覧ください。
• アラート ポリシーに関する説明は、アラートの概要をご覧ください。

以降のセクションでは、指標モードで使用される形式の違いと、Monitoring で使用するために取り込まれたデータをクエリする方法について説明します。

OTLP 指標の取り込み形式

OTLP レシーバーには、指標データの取り込みに使用される API を指定する metrics_mode オプションが用意されています。デフォルトでは、レシーバーは Prometheus API を使用します。metrics_mode オプションのデフォルト値は googlemanagedprometheus です。指標は、Managed Service for Prometheus で使用されている API を使用して取り込まれます。

代わりに、Cloud Monitoring API に指標データを送信するようにレシーバーを構成できます。Monitoring API にデータを送信するには、次の例に示すように metrics_mode オプションの値を googlecloudmonitoring に設定します。

combined:
  receivers:
    otlp:
      type: otlp
      metrics_mode: googlecloudmonitoring

OTLP 指標の Cloud Monitoring へのマッピング方法は、使用する取り込み形式によって決まります。Monitoring では、どちらの指標形式でもグラフ、ダッシュボード、アラート ポリシーを作成できますが、クエリでは異なる指標を参照します。

取り込みの形式によって、データの取り込みに使用される料金モデルも決まります。

以下のセクションでは、料金、Prometheus API によって取り込まれる指標、Monitoring API によって取り込まれる同じ指標の構造上の違い、クエリで指標を参照する方法について説明します。

料金と割り当て

OTLP 指標の請求方法は、使用する取り込み形式によって決まります。

• Prometheus API: Prometheus API を使用してアプリケーションの指標を取り込む場合、データは Managed Service for Prometheus を使用して指標が取得されたようにみなされ、サンプルベースの料金が適用されます。

  • 現在の料金については、Cloud Monitoring の料金の概要をご覧ください。
  • サンプルのカウントと費用見積もりの詳細については、取り込まれたサンプル数に基づく料金の例をご覧ください。

• Monitoring API: Monitoring API を使用してアプリケーションの指標を取り込む場合、データは、Ops エージェントがある他のインテグレーションからのデータのように、ボリュームベースの料金が適用されます。

  • 現在の料金については、Cloud Monitoring の料金の概要をご覧ください。
  • 取り込み量と費用見積もりの詳細については、取り込まれたバイト数に基づく料金の例をご覧ください。

OTLP レシーバーを使用して取り込まれた指標は、Cloud Monitoring に取り込まれるときにカスタム指標の一種とみなされ、カスタム指標の割り当てと上限が適用されます。

指標の構造

Cloud Monitoring では、指標記述子と呼ばれるスキーマを使用して指標データの形式を記述します。指標記述子には、指標の名前、指標値のデータ型、各値と以前の値の関係、値に関連付けられたラベルが含まれます。Prometheus API を使用して指標を取り込むように OTLP レシーバーを構成する場合、作成される指標記述子は、Monitoring API の使用時に作成される指標記述子と異なります。

Prometheus API: Prometheus API を使用してアプリケーションの指標を取り込む場合、各指標は標準の OpenTelemetry から Prometheus への変換を使用して変換され、Cloud Monitoring のモニタリング対象リソースタイプにマッピングされます。

• 変換には次の変更が含まれます。
  • OTLP 指標名には接頭辞 prometheus.googleapis.com/ が付けられます。
  • OTLP 指標名に含まれるピリオド（.）などの英数字以外の文字は、アンダースコア（_）に置き換えられます。
  • OTLP 指標名には、/gauge や /counter などの指標の種類を示す文字列が末尾に付加されます。
• OTLP リソースの値が入力された次のラベルが指標に追加されます。
  • instance_name: host.name リソース属性の値。
  • machine_type: host.type リソース属性の値。

• 指標の測定値で記録されるモニタリング対象リソースは、汎用の prometheus_target タイプです。生成された Prometheus 時系列には、prometheus_target リソースの次のラベルが含まれ、OTLP リソースからの値が入力されます。

  • location: cloud.availability_zone リソース属性の値。
  • namespace: host.id リソース属性の値。

  prometheus_target リソースタイプには次のラベルも含まれています。

  • project_id: Ops エージェントが実行されている Google Cloud プロジェクトの ID（my-project など）。
  • cluster: Ops エージェントによって指標が収集される場合、値は常に __gce__ です。

受信する OTLP データにラベル値に使用されるリソース属性がない場合、その値は Ops エージェントを実行している VM に関する情報から取得されます。この動作により、こうしたリソース属性のない OTLP データは、Ops エージェント Prometheus レシーバーによって収集されたデータと同じラベルで表示されます。

Monitoring API: Monitoring API を使用してアプリケーションの指標を取り込む場合、各指標は次のように処理されます。

• OTLP 指標名には文字列 workload.googleapis.com/ が付加されます（OTLP 指標名に、この文字列や、custom.googleapis.com などの別の有効な指標ドメインがすでに含まれている場合を除く）。workload ドメインの使用をおすすめします。
• 指標の測定値で記録されるモニタリング対象リソースは、Compute Engine の仮想マシンタイプ gce_instance です。

以下の例では、1 組の OpenTelemetry 指標の指標記述子を示します。指標は、Go OpenTelemetry 指標ライブラリを使用するアプリケーションによって作成されます。[Prometheus API] タブでは、OTLP レシーバーがデフォルトの Prometheus 指標モードを使用するときに作成される指標記述子を示します。[Monitoring API] タブには、OTLP レシーバーが googlecloudmonitoring 指標モードを使用するときに作成される指標記述子を示します。

指標を作成するアプリケーションは変更されません。唯一の変更は、OTLP レシーバーで使用される指標モードです。

アプリケーションは、64 ビット浮動小数点値を記録する OTLP ゲージ指標 otlp.test.gauge を作成します。次のタブに、各取り込み API が作成する指標記述子を示します。

{
  "name": "projects/PROJECT_ID/metricDescriptors/prometheus.googleapis.com/otlp_test_gauge/gauge",
  "labels": [
    {
      "key": "instance_name"
    },
    {
      "key": "machine_type"
    }
  ],
  "metricKind": "GAUGE",
  "valueType": "DOUBLE",
  "type": "prometheus.googleapis.com/otlp_test_gauge/gauge",
  "monitoredResourceTypes": [
    "prometheus_target"
  ]
}

{
  "name": "projects/PROJECT_ID/metricDescriptors/workload.googleapis.com/otlp.test.gauge",
  "labels": [
    {
      "key": "instrumentation_source"
    }
  ],
  "metricKind": "GAUGE",
  "valueType": "DOUBLE",
  "type": "workload.googleapis.com/otlp.test.gauge",
  "monitoredResourceTypes": [
    "gce_instance",
    ...many other types deleted...
  ]
}

アプリケーションは、増加する 64 ビット浮動小数点値を記録する OTLP カウンタ指標 otlp.test.cumulative を作成します。次のタブに、各取り込み API が作成する指標記述子を示します。

{
  "name": "projects/PROJECT_ID/metricDescriptors/prometheus.googleapis.com/otlp_test_cumulative/counter",
  "labels": [
    {
      "key": "instance_name"
    },
    {
      "key": "machine_type"
    }
  ],
  "metricKind": "CUMULATIVE",
  "valueType": "DOUBLE",
  "type": "prometheus.googleapis.com/otlp_test_cumulative/counter",
  "monitoredResourceTypes": [
    "prometheus_target"
  ]
}

{
  "name": "projects/PROJECT_ID/metricDescriptors/workload.googleapis.com/otlp.test.cumulative",
  "labels": [
    {
      "key": "instrumentation_source"
    }
  ],
  "metricKind": "CUMULATIVE",
  "valueType": "DOUBLE",
  "type": "workload.googleapis.com/otlp.test.cumulative",
  "monitoredResourceTypes": [
    "gce_instance",
    ...many other types deleted...
  ]
}

次の表は、OTLP 指標の取り込みに使用する API による形式の違いの一部をまとめたものです。

取り込み形式とクエリ

OTLP レシーバーで使用される指標モードは、グラフ、ダッシュボード、アラート ポリシーの作成時に Cloud Monitoring で結果の指標をクエリする方法に影響します。

Cloud Monitoring でグラフ、ダッシュボード、アラート ポリシーを構成すると、その構成にはグラフ、ダッシュボード、アラート ポリシーが操作するデータのクエリが含まれます。

Cloud Monitoring は、指標データを対象とする次のツールをサポートしています。

• Metrics Explorer、ダッシュボード ビルダー インターフェース、アラート ポリシー構成インターフェースなどのツールに組み込まれるクエリビルダー ベースのインターフェース。
• Monitoring Query Language（MQL）: Cloud Monitoring に固有のテキストベースのクエリ言語。
• Prometheus Query Language（PromQL）: オープンソースの Prometheus で使用されるテキストベースのクエリ言語。

これらのツールを使用して OTLP 指標をクエリする方法については、以下をご覧ください。

• Prometheus API を使用して取り込まれた OTLP 指標をクエリする
• Monitoring API を使用して取り込まれた OTLP 指標をクエリする

Prometheus API を使用して取り込まれた OTLP 指標をクエリする

このセクションでは、Prometheus API（OTLP レシーバーのデフォルトの指標モード）を使用して取り込まれた OTLP 指標をクエリする方法について説明します。

クエリは、指標構造で説明されている OTLP 指標に基づいています。

• otlp.test.gauge: 64 ビット浮動小数点値を記録する OTLP ゲージ指標。
• otlp.test.cumlative: 64 ビット浮動小数点値の増加を記録する OTLP カウンタ指標。

これらの指標は、次の指標タイプとともに Cloud Monitoring に取り込まれます。これらの指標タイプは名前として機能します。

• prometheus.googleapis.com/otlp_test_gauge/gauge
• prometheus.googleapis.com/otlp_test_cumulative/counter

Prometheus API を使用して取り込まれた指標は、モニタリング対象リソースタイプ prometheus_target に対して書き込まれます。

このタブでは、Google Cloud コンソールを使用して指標に対してクエリを実行する基本的なクエリを示します。以下の例では Metrics Explorer を使用していますが、ダッシュボードやアラート ポリシーでも原則は同じです。

Monitoring API を使用して取り込まれた OTLP 指標をクエリする

このセクションでは、Monitoring API を使用して取り込まれた OTLP 指標をクエリする方法について説明します。Cloud Monitoring API を選択するには、OTLP レシーバーの metrics_mode フィールドの値を googlecloudmonitoring に設定します。

クエリは、指標構造で説明されている OTLP 指標に基づいています。

• otlp.test.gauge: 64 ビット浮動小数点値を記録する OTLP ゲージ指標。
• otlp.test.cumlative: 64 ビット浮動小数点値の増加を記録する OTLP カウンタ指標。

これらの指標は、次の指標タイプとともに Cloud Monitoring に取り込まれます。これらの指標タイプは名前として機能します。

• workload.googleapis.com/otlp.test.gauge
• workload.googleapis.com/otlp.test.cumulative

Monitoring API を使用して取り込まれた指標は、モニタリング対象リソースタイプ gce_instance に対して書き込まれます。

このタブでは、Google Cloud コンソールを使用して指標に対してクエリを実行する基本的なクエリを示します。以下の例では Metrics Explorer を使用していますが、ダッシュボードやアラート ポリシーでも原則は同じです。

Cloud Monitoring で指標の使用状況と診断情報を表示する

Cloud Monitoring の [指標の管理] ページでは、オブザーバビリティに影響を与えることなく、課金対象の指標に費やす金額を制御するために役立つ情報が提供されます。[指標の管理] ページには、次の情報が表示されます。

• 指標ドメイン全体と個々の指標での、バイトベースとサンプルベースの両方の課金に対する取り込み量。
• 指標のラベルとカーディナリティに関するデータ。
• 各指標の読み取り回数。
• アラート ポリシーとカスタム ダッシュボードでの指標の使用。
• 指標書き込みエラーの割合。

また、指標の管理を使用して不要な指標を除外し、取り込みのコストを削減することもできます。

[指標の管理] ページを表示するには、次の操作を行います。

1. Google Cloud コンソールで、 query_stats[指標の管理] ページに移動します。

   [指標の管理] に移動

   検索バーを使用してこのページを検索する場合は、小見出しが [Monitoring] の結果を選択します。

2. ツールバーで時間枠を選択します。デフォルトでは、[指標の管理] ページには、過去 1 日間に収集された指標に関する情報が表示されます。

[指標の管理] ページの詳細については、指標の使用状況の表示と管理をご覧ください。

OTLP トレースを収集する

トレースを収集するように Ops エージェントを構成しても、アプリケーションの実行時に Cloud Trace にトレースが表示されない場合は、エージェントが使用する Compute Engine サービス アカウントに対して追加のロールの付与が必要になることがあります。デフォルトでは、サービス アカウントは指標とログの書き込みに必要なロールを付与されますが、トレースに必要なロールは付与されません。

以降のセクションでは、必要な Cloud Trace の権限をサービス アカウントに付与する方法について説明します。

サービス アカウントに付与されているロールを確認する

サービス アカウントに付与されているロールを表示するには、次の gcloud projects get-iam-policy コマンドを実行します。

gcloud projects get-iam-policy PROJECT_ID --format="table(bindings.role)" --flatten="bindings[].members" --filter="bindings.members:SERVICE_ACCT_NAME@PROJECT_ID.iam.gserviceaccount.com"

出力は次のようになります。

ROLE
roles/logging.logWriter
roles/monitoring.metricWriter

出力に roles/cloudtrace.agent または roles/cloudtrace.admin が含まれている場合、サービス アカウントにはトレースを書き込むのに十分な権限があります。これらのロールのいずれかをサービス アカウントに付与するには、次のセクションをご覧ください。

サービス アカウントに Cloud Trace ロールを付与する

サービス アカウントの場合、通常は Cloud Trace エージェントのロール roles/cloudtrace.agent が適切なロールです。このロールをサービス アカウントに付与するには、次の gcloud projects add-iam-policy-binding コマンドを実行します。

gcloud projects add-iam-policy-binding PROJECT_ID --member "serviceAccount:SERVICE_ACCT_NAME@PROJECT_ID.iam.gserviceaccount.com" --role="roles/cloudtrace.agent"

次に、変更が行われたことを確認するために、gcloud projects get-iam-policy コマンドを実行します。

gcloud projects get-iam-policy PROJECT_ID --format="table(bindings.role)" --flatten="bindings[].members" --filter="bindings.members:SERVICE_ACCT_NAME@PROJECT_ID.iam.gserviceaccount.com"

出力には、roles/cloudtrace.agent が含まれています。

ROLE
roles/cloudtrace.agent
roles/logging.logWriter
roles/monitoring.metricWriter

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

Ops エージェントが Cloud Trace へのデータの書き込みに使用するサービス アカウントを承認すると、OpenTelemetry ベースのアプリケーションを実行するときに、Cloud Trace にトレースが表示されます。

OTLP レシーバーを無効にする

Ops エージェントを使用して OTLP 指標とトレースの両方を収集していて、指標とトレースの両方の収集ではなく、いずれかの収集を無効にする場合は、次のようにします。

1. ユーザー構成ファイル config.yaml に次のいずれかの変更を行い、指標またはトレースの収集を無効にします。

   • metrics サービスから otlp パイプラインを削除します。
   • traces サービスから otlp パイプラインを削除します。

2. Ops エージェントを再起動します。

Ops エージェントによる OTLP 指標とトレースの収集を無効にするには、次の操作を行います。

1. ユーザー構成ファイルから OTLP 設定を削除します。

   • otlp レシーバーを含む combined セクション全体を削除します。
   • metrics サービスから otlp パイプラインを削除します。
   • traces サービス全体を削除します。

2. Ops エージェントを再起動します。

次のステップ

アプリケーション指標とトレースが取り込まれたら、Google Cloud コンソールを使用して、データをモニタリングして分析できます。

• ダッシュボードと作成可能なグラフの種類については、ダッシュボードとグラフをご覧ください。
• アラート ポリシーの詳細については、アラート ポリシーの使用をご覧ください。
• トレースデータの分析については、トレースを検索して調査するをご覧ください。