Google は AI 技術を使用して、コンテンツをご希望の言語に翻訳しています。AI 翻訳には誤りが含まれる場合があります。

コレクタを移行して OTLP エクスポータを使用する

Telemetry（OTLP）API は、OpenTelemetry Protocol の実装です。OTLP のサポートにより、汎用的な otlphttp エクスポータと otlp_grpc/otlp_logs エクスポータをコレクタ構成に追加して、ベンダー固有のエクスポータを回避できます。アプリケーションは、ログ、指標、トレースデータを Telemetry API に送信できます。

このガイドは、コレクタの構成で googlecloud エクスポータまたは googlemanagedprometheus エクスポータを使用している場合に適用されます。

ログデータ: googlecloud エクスポータから otlp_grpc/otlp_logs エクスポータに移行します。
指標データ: googlemanagedprometheus エクスポータから otlphttp エクスポータに移行します。
トレースデータ: googlecloud エクスポータから otlphttp エクスポータに移行します。

OTLP エクスポータに移行する手順は次のとおりです。

Telemetry API を有効にする
コレクタサービスアカウントを承認する
GOOGLE_CLOUD_PROJECT 環境変数を設定する
googleclientauth 拡張機能を追加する
otlphttp エクスポータと otlp_grpc/otlp_logs エクスポータを追加する
プロセッサを追加する
サービスパイプラインを更新する
構成を検証する
ダッシュボードとアラートポリシーを移行する
ベンダー固有のエクスポーターを削除する

Telemetry API を有効にする

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

gcloud services enable telemetry.googleapis.com

コレクタサービスアカウントを承認する

コレクタは、実行される環境の ID を使用して Google Cloud API に対して認証を行います。コレクタを実行するサービスアカウントには、Telemetry API を使用してログ、指標、トレースデータを書き込む権限が必要です。また、Telemetry API はコンシューマー API であるため、API 呼び出しで割り当てが使用される Google Cloud プロジェクトを明示的に指定し、そのプロジェクトの割り当てを使用するために必要な権限をサービスアカウントに付与する必要があります。

必要なロール

コレクタを実行しているサービスアカウントにログ、指標、トレースデータを送信するために必要な権限が付与されるように、プロジェクトでコレクタを実行しているサービスアカウントに次の IAM ロールを付与するよう管理者に依頼してください。

Cloud テレメトリー書き込み（roles/telemetry.writer）
Service Usage コンシューマー（roles/serviceusage.serviceUsageConsumer）

これらの事前定義ロールには、ログ、指標、トレースデータを送信するために必要な権限が含まれています。必要とされる正確な権限については、「必要な権限」セクションを開いてご確認ください。

必要な権限

ログ、指標、トレースデータを送信するには、次の権限が必要です。

logging.logEntries.create
monitoring.timeSeries.create
telemetry.traces.write
serviceusage.services.use

Kubernetes サービスアカウント

Workload Identity Federation for GKE を使用して Google Kubernetes Engine（GKE）にコレクタをデプロイする場合は、Kubernetes サービスアカウントに必要なロールを付与します。

API 割り当てが Telemetry API 呼び出しの宛先と同じ Google Cloud プロジェクトから取得されている場合は、次のコマンドを使用して必要なロールを付与できます。コマンドを実行する前に、PROJECT_ID をプロジェクトの ID に置き換えます。ただし、別の割り当てプロジェクトを使用する場合は、2 番目のコマンドの PROJECT_ID を割り当てプロジェクトの ID に置き換えます。

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

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

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

Workload Identity Federation for GKE のサービスアカウント

Workload Identity Federation for GKE のサービスアカウントを構成した場合は、Google Cloud Managed Service for Prometheus ドキュメントのコマンドを使用して、次の変更を加えてサービスアカウントを認可できます。

gmp-test-sa をサービスアカウントの名前に置き換えます。
コマンドを実行して、ログデータ、指標データ、トレースデータを書き込むために必要なロールを付与します。

その他のサービスアカウント

Compute Engine VM または GKE の外部でコレクタを実行する場合は、デプロイで使用する Google Cloud サービスアカウントに必要なロールを付与します。

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

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

env:
- name: GOOGLE_CLOUD_PROJECT
  value: PROJECT_ID

`googleclientauth` 拡張機能を追加する

コレクタ構成に googleclientauth 拡張機能を追加します。Telemetry API はコンシューマー API であり、 Google Cloud プロジェクトと割り当てプロジェクトの両方を指定する必要があります。結果は次のようになります。

extensions:
  googleclientauth:
    project: ${GOOGLE_CLOUD_PROJECT}
    quota_project: ${GOOGLE_CLOUD_PROJECT}

`otlphttp` エクスポータと `otlp_grpc/otlp_logs` エクスポータを追加する

otlphttp エクスポータを使用して OTLP 形式の指標データとトレースデータをプロジェクトに送信し、otlp_grpc/otlp_logs エクスポータを使用してログデータを送信します。両方のエクスポータを googleclientauth 拡張機能で構成してください。

結果は次のようになります。

exporters:
  # ... existing content ...
  otlphttp:
    encoding: proto
    endpoint: https://telemetry.googleapis.com
    auth:
      authenticator: googleclientauth
  otlp_grpc/otlp_logs:
    auth:
      authenticator: googleclientauth
    balancer_name: pick_first
    endpoint: telemetry.googleapis.com:443

otlp_grpc/otlp_logs エクスポータの場合、endpoint フィールドは host:port 形式を使用して指定する必要があります。

プロセッサを追加する

このセクションでは、コレクタに追加する必要があるプロセッサを一覧表示します。使用できるプロセッサは他にもあります。たとえば、Google が構築した OpenTelemetry Collector のコレクタ構成には、通常、memory_limiter プロセッサと指標データを変換するプロセッサが含まれます。例については、GKE 上の Google が構築した OpenTelemetry Collector をご覧ください。

`resource/gcp_project_id` プロセッサを追加する

Google Cloud プロジェクトに関する情報をキャプチャする resource プロセッサを追加します。

  resource/gcp_project_id:
    attributes:
      - action: insert
        value: ${GOOGLE_CLOUD_PROJECT}
        key: gcp.project_id

`resourcedetection` プロセッサを追加する

Google Cloudで実行している場合は、resourcedetection プロセッサの追加を検討してください。このプロセッサは、アーキテクチャに関する情報を自動的に検出できます。

次の構成では、標準の OpenTelemetry 環境変数を検索し、 Google Cloud メタデータサーバーにクエリを実行して、インフラストラクチャに関する情報を収集します。

  resourcedetection:
    detectors: ["env", "gcp"]

`batch` プロセッサを追加する

テレメトリーを Google Cloud プロジェクトに効率的に送信するには、batch プロセッサを使用することをおすすめします。

たとえば、Google が構築した OpenTelemetry Collector コレクタは、バッチプロセッサに次の構成を使用します。

batch:
  send_batch_max_size: 200
  send_batch_size: 200
  timeout: 5s

`metricstarttime` プロセッサを追加する

構成に metricstarttime プロセッサを追加します。このプロセッサは、累積指標に開始時間と観測時間の両方が含まれるようにします。デフォルトでは、Prometheus 指標には現在の時刻のみが含まれます。したがって、このプロセッサを省略してアプリケーションが Prometheus 指標を生成すると、指標データが拒否されるか、データスパイクが発生する可能性があります。

コレクタが Prometheus 指標を受信する場合は、このプロセッサを追加する必要があります。

processors:
  # This processor ensures the start time is set for Prometheus metrics.
  # Set in the pipeline before the k8sattributes processor, if used.
  # No-op for OTLP metrics.
  metricstarttime:
    strategy: subtract_initial_point

変換プロセッサを追加する

ログデータに計測のソースとバージョンを保持するには、次の transform プロセッサを追加します。

  transform/otlp_grpc/preserve_instrumentation_source_version:
    error_mode: ignore
    log_statements:
      - context: log
        statements:
          - set(attributes["instrumentation_source"], instrumentation_scope.name) where instrumentation_scope.name != ""
          - set(attributes["instrumentation_version"], instrumentation_scope.version) where instrumentation_scope.version != ""
          - set(attributes["service.name"], resource.attributes["service.name"]) where resource.attributes["service.name"] != nil
          - set(attributes["service.namespace"], resource.attributes["service.namespace"]) where resource.attributes["service.namespace"] != nil
          - set(attributes["service.instance.id"], resource.attributes["service.instance.id"]) where resource.attributes["service.instance.id"] != nil

サービスパイプラインを更新する

次に、otlp_grpc/otlp_logs エクスポーターと otlphttp エクスポーターを使用するようにコレクタのパイプラインを更新します。ログデータとトレースデータの場合、これらの手順では、現在のエクスポータが適切な OTLP エクスポータに置き換えられます。指標データの場合、この手順では二重書き込みが発生します。この方法を使用すると、OTLP エクスポータが指標データを Google Cloud プロジェクトに送信していることを確認できます。また、元のエクスポータからのデータストリームを停止する前に、グラフとアラートポリシーを更新することもできます。

コレクタのパイプライン構成を次のように変更します。

service の項目に googleclientauth 拡張機能を追加します。
ログパイプラインの場合は、googlecloud/logging を otlp_grpc/otlp_logs に置き換えてから、次のプロセッサをパイプラインのプロセッサリストに追加します。
- resource/gcp_project_id
- transform/otlp_grpc/preserve_instrumentation_source_version
- resourcedetection（このプロセッサを追加した場合）
- batch
この構成では、ログデータの単一書き込みが実行されます。ログデータを二重書き込みする場合は、otlp_grpc/otlp_logs エクスポータをエクスポータのリストに追加します。
指標パイプラインの場合は、googlemanagedprometheus エクスポータとともに otlphttp エクスポータをパイプラインのエクスポータリストに追加し、次のプロセッサを追加します。
- resource/gcp_project_id
- metricstarttime
- resourcedetection（このプロセッサを追加した場合）
- batch
この構成では、指標データの二重書き込みが行われます。指標データストリームを検証し、グラフとアラートポリシーを更新したら、Prometheus エクスポータを削除します。
トレースパイプラインで、現在のエクスポータを otlphttp エクスポータに置き換え、次のプロセッサを追加します。
- resource/gcp_project_id
- resourcedetection（このプロセッサを追加した場合）
- batch
この構成では、トレースデータの単一書き込みが実行されます。

これらの変更の結果は次のようになります。

service:
  extensions: ["googleclientauth"]
  pipelines:
    logs:
      receivers: ["otlp"]
      processors:
        - resourcedetection
        - resource/gcp_project_id
        - transform/otlp_grpc/preserve_instrumentation_source_version
        - batch
      exporters: ["otlp_grpc/otlp_logs"]
    metrics:
      receivers: ["otlp"]
      processors:
        - resourcedetection
        - resource/gcp_project_id
        - metricstarttime
        - batch
      exporters: ["googlemanagedprometheus", "otlphttp"]
    traces:
      receivers: ["otlp"]
      processors:
        - resourcedetection
        - resource/gcp_project_id
        - batch
      exporters: ["otlphttp"]

上記のスニペットでは、ログデータ、指標データ、トレースデータに OTLP レシーバを使用しています。コレクタの構成は異なる場合があります。たとえば、構造化ログデータを書き込むアプリケーションがある場合は、filelog レシーバーが適切です。

構成を検証する

デプロイを再起動し、otlphttp エクスポータと otlp_grpc/otlp_logs エクスポータが Google Cloud プロジェクトにデータを送信していることを確認します。構成を確認するには、次の操作を行います。

テレメトリーデータの書き込みに関連するエラーについてログエントリをクエリします。
Cloud Logging API、Cloud Monitoring API、Telemetry API のエラー率を表示します。
Metrics Explorer を使用して時系列を表示します。

ダッシュボードとアラートポリシーを移行する

グラフとダッシュボードを次のように更新します。

グラフまたはアラートポリシーを使用して Cloud Logging API または Cloud Monitoring API の使用状況をモニタリングしている場合は、Telemetry API の使用状況をモニタリングするためのグラフまたはアラートポリシーを追加で作成します。
指標レシーバに otlp レシーバが含まれている場合、またはコレクタが UTF-8 文字を含む Prometheus 指標をスクレイピングする場合は、グラフとダッシュボードを更新します。otlphttp エクスポータは、googlemanagedprometheus エクスポータとは異なる指標を生成します。詳細については、エクスポートされた指標の形式の違いをご覧ください。

コレクタが Prometheus 指標データのみを受信する場合は、グラフとダッシュボードを更新する必要はありません。
指標パイプラインに prometheus レシーバが含まれている場合、otlphttp エクスポータと googlemanagedprometheus エクスポータによって生成された指標間でデータストリームの競合が発生します。この競合を解決するには、googlemanagedprometheus エクスポータを削除します。

エクスポートされた指標の形式の違い

指標ベースのグラフとアラートポリシーの更新が必要なのは、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 バージョンの指標の結果を手動で統合する必要があります。
テレメトリー 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 指標名を参照するオープンソースアセットを使用できなくなります。

ベンダー固有のエクスポータを削除する

新しいデータストリームを検証し、ダッシュボードとアラートポリシーを更新したら、コレクタ構成から googlecloud/logging エクスポータと googlemanagedprometheus エクスポータを削除します。構成から削除されたエクスポーターでのみ使用されていたプロセッサを削除する必要がある場合もあります。

エクスポートのリストとサービスパイプラインの両方を更新する必要があります。

exporters:
  otlphttp: [...]
  otlp_grpc/otlp_logs: [...]

...
service:
  extensions: ["googleclientauth"]
  pipelines:
    logs:
      receivers: ["otlp"]
      processors: [...]
      exporters: ["otlp_grpc/otlp_logs"]
    metrics:
      receivers: ["otlp"]
      processors: [...]
      exporters: ["otlphttp"]
    traces:
      receivers: ["otlp"]
      processors: [...]
      exporters: ["otlphttp"]

トラブルシューティング

このセクションでは、コレクタの構成を移行する際に発生する可能性のあるエラーの解決方法について説明します。

指標データがない、または指標データが急増している

指標データが欠落しているか、スパイクが含まれている場合は、コレクタの構成に metricstarttime プロセッサを追加したことを確認します。詳細については、metricstarttime プロセッサを追加するをご覧ください。

Monitoring のコレクタログ、システムログ、データアクセス監査ログを確認することもできます。たとえば、時系列への書き込みが失敗すると、失敗の理由を含むデータアクセス監査ログが生成されます。

時系列の書き込みに関するエラーメッセージ

時系列へのデータの書き込みが失敗すると、システムはエラーメッセージを生成します。これらのメッセージは、書き込みが失敗した理由と問題の解決方法を把握するのに役立ちます。

値の不一致を示すエラーメッセージ:
```
"One or more TimeSeries could not be written: Value type DOUBLE does not match metric descriptor value type INT64."
```
このエラーは、以前に INT64 target_info 指標を送信した場合に発生します。これは、Telemetry API がすべての指標の値の型を DOUBLE に設定するためです。長期的な最適な解決策は、INT64 target_info 指標の指標記述子を削除することです。この記述子を指標スコープから削除するには、この Golang スクリプトを使用します。
複数のソースが時系列データを書き込んでいることを示すエラーメッセージ:
```
"One or more TimeSeries could not be written: Points must be written in order. One or more of the points specified had an older end time than the most recent point."
```
この問題を解決するには、コレクタの構成から googlemanagedprometheus エクスポータを削除します。詳細については、ベンダー固有のエクスポータを削除するをご覧ください。

次のステップ

コレクタベースの計測サンプルの概要は、ダウンロードしてインストールできるサンプルアプリケーションを指します。各サンプルアプリケーションには、Telemetry API を使用して指標データとトレースデータをエクスポートする完全なコレクタが含まれています。
Google が構築した OpenTelemetry Collector を Google Kubernetes Engine にデプロイするには、完全な Collector 構成が含まれています。

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

Telemetry API を有効にする

コレクタ サービス アカウントを承認する

必要なロール

必要な権限

Kubernetes サービス アカウント

Workload Identity Federation for GKE のサービス アカウント

その他のサービス アカウント

GOOGLE_CLOUD_PROJECT 環境変数を設定する

googleclientauth 拡張機能を追加する

otlphttp エクスポータと otlp_grpc/otlp_logs エクスポータを追加する