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 エージェントを構成するには、次の操作を行います。

Ops エージェントのユーザー構成ファイルを変更して OTLP レシーバーを含めます。
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 エージェントを再起動する必要があります。

Linux

エージェントを再起動するには、インスタンスで次のコマンドを実行します。
```
sudo systemctl restart google-cloud-ops-agent
```
エージェントが再起動したことを確認するには、次のコマンドを実行して「Metrics Agent」と「Logging エージェント」のコンポーネントが起動したことを確認します。
```
sudo systemctl status "google-cloud-ops-agent*"
```

Windows

RDP または同様のツールを使用してインスタンスに接続し、Windows にログインします。
PowerShell アイコンを右クリックし、[管理者として実行] を選択して、管理者権限で PowerShell ターミナルを開きます。
エージェントを再起動するには、次の PowerShell コマンドを実行します。
```
Restart-Service google-cloud-ops-agent -Force
```
エージェントが再起動したことを確認するには、次のコマンドを実行して「Metrics Agent」と「Logging エージェント」のコンポーネントが起動したことを確認します。
```
Get-Service google-cloud-ops-agent*
```

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 が作成する指標記述子を示します。

Prometheus 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"
  ]
}

Monitoring API

{
  "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 が作成する指標記述子を示します。

Prometheus 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"
  ]
}

Monitoring API

{
  "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 による形式の違いの一部をまとめたものです。

	Prometheus API	Monitoring API
指標ドメイン	`prometheus.googleapis.com`	`workload.googleapis.com`
OTLP 指標名	取り込み中に変更	そのまま使用
モニタリング対象リソース	`prometheus_target`	`gce_instance`

取り込み形式とクエリ

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 を使用していますが、ダッシュボードやアラートポリシーでも原則は同じです。

クエリビルダーインターフェース

クエリビルダーインターフェースを使用して指標データをクエリするには、検索可能なフィールドに入力し、指標タイプとモニタリング対象リソースタイプを指定します。リソースタイプは指標タイプよりもはるかに少ないため、通常はリソースタイプを検索してから、関連する指標のメニューを使用すると、指標タイプを効率よく見つけることができます。

検索フィールドに「prometheus」と入力すると、表示名「Prometheus Target」で表示される prometheus_target モニタリング対象リソースと、リソースに書き込む一連の指標が結果に含まれます。指標は名前で分類されます。2 つの指標の例は Otlp カテゴリとして表示されます。Prometheus/otlp_test_cumulative/counter または Prometheus/otlp_test_gauge/gauge を選択できます。

クエリビルダーの使用方法については、メニューを使用してクエリを作成するをご覧ください。

次のスクリーンショットは、prometheus.googleapis.com/otlp_test_gauge/gauge 指標をクエリした結果を示しています。

ビルダーベースの Metrics Explorer グラフ。Prometheus API を使用して取り込まれた OTLP ゲージ指標が表示されています。

次のスクリーンショットは、prometheus.googleapis.com/otlp_test_cumulative/counter 指標をクエリした結果を示しています。

ビルダーベースの Metrics Explorer グラフ。Prometheus API を使用して取り込まれた OTLP カウンタ指標が表示されています。

MQL

MQL を使用して指標データをクエリするには、fetch ステートメントを使用して、指標タイプとモニタリング対象リソースタイプを指定します。この 2 つのタイプは :: で区切ります。指標の例に対する簡単な MQL クエリは次のようになります。

fetch prometheus.googleapis.com/otlp_test_gauge/gauge::prometheus_target
fetch prometheus.googleapis.com/otlp_test_cumulative/counter::prometheus_target

MQL クエリの作成の詳細については、サンプル MQL クエリをご覧ください。

次のスクリーンショットは、prometheus.googleapis.com/otlp_test_gauge/gauge 指標をクエリした結果を示しています。

Prometheus API を使用して取り込まれた OTLP ゲージ指標が表示されている MQL Metrics Explorer グラフ。

次のスクリーンショットは、prometheus.googleapis.com/otlp_test_cumulative/counter 指標をクエリした結果を示しています。

Prometheus API を使用して取り込まれた OTLP カウンタ指標が表示されている MQL Metrics Explorer グラフ。

PromQL

PromQL で Prometheus API を使用して取り込まれた指標データをクエリする場合は、元の OTLP 指標名の変更形式を指定するだけで済みます。接頭辞 prometheus.googleapis.com/ や接尾辞を指定する必要はありません。

1 つのモニタリング対象リソースタイプに対してのみ指標を書き込むことができる場合は、リソースを指定する必要はありません。指標構造の説明にあるように、Prometheus API を使用して取り込まれる OTLP 指標は、prometheus_target モニタリング対象リソースタイプに対してのみ書き込まれます。指標の例に対する簡単な PromQL クエリは次のようになります。

otlp_test_gauge
otlp_test_cumulative

Prometheus API で取り込まれた指標に Cloud Monitoring の PromQL を使用してクエリを実行する方法の詳細については、Cloud Monitoring の Google Cloud Managed Service for Prometheus データをご覧ください。PromQL 言語の詳細については、Prometheus のクエリをご覧ください。

次のスクリーンショットは、prometheus.googleapis.com/otlp_test_gauge/gauge 指標をクエリした結果を示しています。

Prometheus API を使用して取り込まれた OTLP ゲージ指標が表示されている PromQL Metrics Explorer グラフ。

次のスクリーンショットは、prometheus.googleapis.com/otlp_test_cumulative/counter 指標をクエリした結果を示しています。

Prometheus API を使用して取り込まれた OTLP カウンタ指標が表示されている PromQL 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 に対して書き込まれます。

クエリビルダーインターフェース

検索フィールドに「gce_instance」と入力すると、表示名「VM インスタンス」のリソースの種類と、リソースに書き込む一連の指標が結果に表示されます。指標は名前で分類されます。2 つの指標の例は Otlp カテゴリとして表示されます。Workload/otlp_test_cumulative または Workload/otlp_test_gauge を選択できます。

クエリビルダーの使用方法については、メニューを使用してクエリを作成するをご覧ください。

次のスクリーンショットは、workload.googleapis.com/otlp.test.gauge 指標をクエリした結果を示しています。

ビルダーベースの Metrics Explorer グラフ。Monitoring API を使用して取り込まれた OTLP ゲージ指標が表示されています。

次のスクリーンショットは、workload.googleapis.com/otlp.test.cumulative 指標をクエリした結果を示しています。

ビルダーベースの Metrics Explorer グラフ。Monitoring API を使用して取り込まれた OTLP カウンタ指標が表示されています。

MQL

fetch workload.googleapis.com/otlp.test.gauge::gce_instance
fetch workload.googleapis.com/otlp.test.cumulative::gce_instance

MQL クエリの作成の詳細については、サンプル MQL クエリをご覧ください。

次のスクリーンショットは、workload.googleapis.com/otlp.test.gauge 指標をクエリした結果を示しています。

Monitoring API を使用して取り込まれた OTLP ゲージ指標が表示されている MQL Metrics Explorer グラフ。

次のスクリーンショットは、workload.googleapis.com/otlp.test.cumulative 指標をクエリした結果を示しています。

Monitoring API を使用して取り込まれた OTLP カウンタ指標が表示されている MQL Metrics Explorer グラフ。

PromQL

Monitoring API を使用して取り込まれた指標データを PromQL でクエリする場合は、指標名を PromQL の規則にマッピングする必要があります。基本的なマッピングルールには次のものがあります。

最初の / を : に置き換えます。
他のすべての特殊文字（. と他の / 文字を含む）は _ に置き換えます。

マッピングルールの詳細については、Cloud Monitoring 指標を PromQL にマッピングするをご覧ください。

サンプル指標のモニタリング指標は、次のように PromQL にマッピングされます。

workload_googleapis_com:otlp_test_gauge
workload_googleapis_com:otlp_test_cumulative

1 つのモニタリング対象リソースタイプに対してのみ指標を書き込むことができる場合は、リソースを指定する必要はありません。指標の例は、gce_instance モニタリング対象リソースタイプに対して記述されていますが、指標構造に記載されているように、考えられる指標タイプは gce_instance だけです。したがって、これらの指標の PromQL クエリには、gce_instance リソースタイプのフィルタを含める必要があります。フィルタを含めるには、マッピングされた指標名の末尾に {monitored_resource="gce_instance"} という文字列を追加します。

Cloud Monitoring での PromQL の使用の詳細については、Cloud Monitoring における PromQL をご覧ください。PromQL 言語の詳細については、Prometheus のクエリをご覧ください。

指標の例に対する簡単な PromQL クエリは次のようになります。

workload_googleapis_com:otlp_test_gauge{monitored_resource="gce_instance"}
workload_googleapis_com:otlp_test_cumulative{monitored_resource="gce_instance"}

次のスクリーンショットは、workload.googleapis.com/otlp.test.gauge 指標をクエリした結果を示しています。

Monitoring API を使用して取り込まれた OTLP ゲージ指標が表示されている PromQL Metrics Explorer グラフ。

次のスクリーンショットは、workload.googleapis.com/otlp.test.cumulative 指標をクエリした結果を示しています。

Monitoring API を使用して取り込まれた OTLP カウンタ指標が表示されている PromQL Metrics Explorer グラフ。

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

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

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

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

Google Cloud コンソールのナビゲーションパネルで [Monitoring] を選択し、次に [指標の管理] を選択します。
[指標の管理] に移動
ツールバーで時間枠を選択します。デフォルトでは、[指標の管理] ページには、過去 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 トレースが表示されています。

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

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

ユーザー構成ファイル config.yaml に次のいずれかの変更を行い、指標またはトレースの収集を無効にします。
- metrics サービスから otlp パイプラインを削除します。
- traces サービスから otlp パイプラインを削除します。
Ops エージェントを再起動します。

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

ユーザー構成ファイルから OTLP 設定を削除します。
- otlp レシーバーを含む combined セクション全体を削除します。
- metrics サービスから otlp パイプラインを削除します。
- traces サービス全体を削除します。
Ops エージェントを再起動します。

次のステップ

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

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

OpenTelemetry Protocol（OTLP）指標とトレースを収集する

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

利点

制限事項

前提条件

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

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

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

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

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

Linux

Windows

OTLP 指標を収集する

OTLP 指標の取り込み形式

料金と割り当て

指標の構造

Prometheus API

Monitoring API

Prometheus API

Monitoring API

取り込み形式とクエリ

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

クエリビルダー インターフェース

MQL

PromQL

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

クエリビルダー インターフェース

MQL

PromQL

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

OTLP トレースを収集する

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

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

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

次のステップ

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

クエリビルダーインターフェース

クエリビルダーインターフェース

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

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