OTLP エクスポータに移行する

このドキュメントでは、既存のエクスポータ（この場合は googlemanagedprometheus エクスポータ）を使用する OpenTelemetry Collector 構成を変更して、otlphttp エクスポータと Telemetry（OTLP）API（telemetry.googleapis.com）を使用する方法について説明します。

Prometheus 指標の OTLP は、OpenTelemetry Collector バージョン 0.140.0 以降を使用する場合にのみ機能します。

Telemetry API を有効にする

otlphttp エクスポータは Telemetry API に書き込むため、プロジェクトでその API を有効にする必要があります。次のコマンドを実行して、Telemetry API を有効にします。

gcloud services enable telemetry.googleapis.com

Kubernetes サービスアカウントを承認する

Kubernetes サービスアカウントには、Telemetry API を使用する権限が必要です。次のコマンドは、必要な Identity and Access Management（IAM）ロールを Kubernetes サービスアカウントに付与します。これらのコマンドは、Workload Identity Federation for GKE を使用していることを前提としています。

export PROJECT_NUMBER=$(gcloud projects describe PROJECT_ID --format="value(projectNumber)")

gcloud projects add-iam-policy-binding projects/PROJECT_ID \
  --role=roles/telemetry.metricsWriter \
  --member=principal://iam.googleapis.com/projects/$PROJECT_NUMBER/locations/global/workloadIdentityPools/PROJECT_ID.svc.id.goog.goog/subject/ns/opentelemetry/sa/opentelemetry-collector \
  --condition=None

PROJECT_ID 変数を Google Cloud プロジェクトの ID に置き換えます。

サービスアカウントの形式が異なる場合は、Google Cloud Managed Service for Prometheus のドキュメントにあるコマンドを使用して、次の変更を加えてサービスアカウントを承認できます。

サービスアカウント名 gmp-test-sa を実際のサービスアカウントに置き換えます。
コマンドを実行して、roles/telemetry.metricsWriter ロールを付与します。

`PROJECT_ID` 環境変数を設定する

コレクタのデプロイで PROJECT_ID 環境変数を設定します。結果は次のようになります。

env:
- name: PROJECT_ID
  value: PROJECT_ID

交換するエクスポータを見つける

構成ファイルで、エクスポータとエクスポータを使用するサービスを見つけます。

exporters:
  googlemanagedprometheus:
service:
  pipelines:
    metrics:
      exporters: [googlemanagedprometheus]

`otlphttp` エクスポータの構成を追加する

このステップでは、otlphttp エクスポーターと metricstarttime プロセッサを構成に追加します。この追加のエクスポータにより、コレクタは指標を二重に書き込みます。

OTLP ネイティブ指標を使用している場合、2 つの方法で作成される指標記述子の構造が異なるため、二重書き込みは問題になりません。これらは別々の指標です。
Prometheus 指標を使用している場合は、googlemanagedpromethus エクスポータを削除するまで競合が発生します。

更新された構成は次のようになります。

exporters:
  googlemanagedprometheus:
  otlphttp:
    encoding: json
    endpoint: https://telemetry.googleapis.com
    auth:
      authenticator: googleclientauth
processors:
  # This processor ensures the start time is set for Prometheus metrics. This must be set in the pipeline before the k8sattributes processor, if used.
  metricstarttime:
    strategy: subtract_initial_point
  resource/gcp_project_id:
    attributes:
    - action: insert
      # Make sure you set the PROJECT_ID environment variable.
      value: ${PROJECT_ID}
      key: gcp.project_id
extensions:
  googleclientauth:
service:
  extensions: [googleclientauth]
  pipelines:
    metrics:
      processors: [resource/gcp_project_id, metricstarttime]
      exporters: [googlemanagedprometheus, otlphttp]

指標を二重書き込みしたら、ダッシュボードとアラートポリシーを更新して、otlphttp エクスポーターによって生成された新しい指標名を使用します。otlphttp エクスポータは、アンダースコアの置換を使用して、指標を「Prometheus スタイル」に名前変更しません。

以前のエクスポータの構成を削除する

otlphttp でエクスポートされた指標を参照するようにダッシュボードとアラートを更新したら、構成から古いエクスポータ（この場合は googlemanagedprometheus）を削除します。修正後の構成は次のようになります。

exporters:
  otlphttp:
    encoding: json
    endpoint: https://telemetry.googleapis.com
    auth:
      authenticator: googleclientauth
processors:
  # This processor ensures the start time is set for Prometheus metrics. This must be set in the pipeline before the k8sattributes processor, if used.
  metricstarttime:
    strategy: subtract_initial_point
  resource/gcp_project_id:
    attributes:
    - action: insert
      # Make sure you set the PROJECT_ID environment variable.
      value: ${PROJECT_ID}
      key: gcp.project_id
extensions:
  googleclientauth:
service:
  extensions: [googleclientauth]
  pipelines:
    metrics:
      processors: [resource/gcp_project_id, metricstarttime]
      exporters: [otlphttp]

必要に応じてダッシュボードとアラートポリシーを移行する

googlemanagedprometheus エクスポータを Prometheus 指標データのみに使用していた場合は、OTLP エクスポータに切り替えても、既存のダッシュボードとアラートポリシーは引き続き機能します。

ただし、googlemanagedprometheus エクスポーターを使用して、元々 OTLP を使用して出力されたデータを収集して送信した場合、または UTF-8 文字を含む Prometheus 指標をスクレイピングした場合は、UTF-8 指標名を使用するようにダッシュボードとアラートを更新する必要があります。

これは、OTLP を使用してエクスポートされた指標と googlemanagedprometheus エクスポータを使用してエクスポートされた指標の間に次の違いがあるためです。

Telemetry API では、指標名にピリオド（.）とスラッシュ（/）を使用できます。googlemanagedprometheus エクスポータは、これらの文字のすべてのインスタンスをアンダースコア（_）文字に変換します。たとえば、prometheus.googleapis.com/foo.bar/gauge という OTLP 指標は、OTLP エクスポータによってそのままエクスポートされますが、googlemanagedprometheus エクスポータによって prometheus.googleapis.com/foo_bar/gauge としてエクスポートされます。

指標が取り込まれると、Cloud Monitoring は名前に基づいて指標記述子を作成します。取り込みパスでのピリオド（.）とスラッシュ（/）文字の処理方法の違いにより、googlemanagedprometheus エクスポータを使用して取り込まれた指標と otlphttp エクスポータを使用して取り込まれた指標で、結果の指標記述子が異なります。両方の取り込みパスを使用すると、2 つの指標セットが作成されます。クエリ時に完全な結果を取得するには、Prometheus バージョンと OTLP バージョンの指標の結果を手動で統合する必要があります。
Telemetry API は、単位が存在する場合に指標名に単位を追加せず、カウンタに _total 接尾辞を追加しません。したがって、Telemetry API を使用して prometheus.googleapis.com/foo/counter としてエクスポートされた指標は、googlemanagedprometheus エクスポーターによって prometheus.googleapis.com/foo_seconds_total/counter としてエクスポートされます。この違いは、_total 接尾辞と _ratio 接尾辞にも適用されます。

指標の違いについて詳しくは、googlemanagedprometheus エクスポーターと Telemetry API の違いをご覧ください。

変換ルールは UTF-8 文字を含む指標には適用されないため、新しい指標名を使用するか、古い指標名と新しい指標名を統合するように、ダッシュボードとアラートポリシーを書き換える必要があります。

googlemanagedprometheus エクスポーターによって収集されたかのように UTF-8 指標の書き込みを続行するために、これらの変換を再作成するプロセッサルールを作成することはおすすめしません。この方法では下位互換性は維持されますが、上位互換性が損なわれ、UTF-8 指標名を参照するオープンソースアセットを簡単に使用できなくなります。

OTLP エクスポータに移行する コレクションでコンテンツを整理 必要に応じて、コンテンツの保存と分類を行います。

Telemetry API を有効にする

Kubernetes サービス アカウントを承認する

PROJECT_ID 環境変数を設定する