Google が構築した OpenTelemetry Collector を Compute Engine にデプロイする

このドキュメントでは、Compute Engine で Google が構築した OpenTelemetry Collector を実行して、計測対象のアプリケーションから OTLP のログ、指標、トレースを収集し、そのデータを Google Cloudにエクスポートする方法について説明します。

始める前に

Google が構築した OpenTelemetry Collector を実行するには、次のリソースが必要です。

Google Cloud アカウントにログインします。 Google Cloudを初めて使用する場合は、 アカウントを作成して、実際のシナリオでの Google プロダクトのパフォーマンスを評価してください。新規のお客様には、ワークロードの実行、テスト、デプロイができる無料クレジット $300 分を差し上げます。

In the Google Cloud console, on the project selector page, select or create a Google Cloud project.

Roles required to select or create a project

• Select a project: Selecting a project doesn't require a specific IAM role—you can select any project that you've been granted a role on.
• Create a project: To create a project, you need the Project Creator role (roles/resourcemanager.projectCreator), which contains the resourcemanager.projects.create permission. Learn how to grant roles.

Note: If you don't plan to keep the resources that you create in this procedure, create a project instead of selecting an existing project. After you finish these steps, you can delete the project, removing all resources associated with the project.

Go to project selector

Verify that billing is enabled for your Google Cloud project.

Cloud Logging API、Cloud Monitoring API、Cloud Trace API を有効にします。

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

API を有効にするには、serviceusage.services.enable 権限を含む Service Usage 管理者 IAM ロール（roles/serviceusage.serviceUsageAdmin）が必要です。ロールを付与する方法を確認する。

API を有効にする

In the Google Cloud console, on the project selector page, select or create a Google Cloud project.

Roles required to select or create a project

• Select a project: Selecting a project doesn't require a specific IAM role—you can select any project that you've been granted a role on.
• Create a project: To create a project, you need the Project Creator role (roles/resourcemanager.projectCreator), which contains the resourcemanager.projects.create permission. Learn how to grant roles.

Note: If you don't plan to keep the resources that you create in this procedure, create a project instead of selecting an existing project. After you finish these steps, you can delete the project, removing all resources associated with the project.

Go to project selector

Verify that billing is enabled for your Google Cloud project.

Cloud Logging API、Cloud Monitoring API、Cloud Trace API を有効にします。

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

API を有効にするには、serviceusage.services.enable 権限を含む Service Usage 管理者 IAM ロール（roles/serviceusage.serviceUsageAdmin）が必要です。ロールを付与する方法を確認する。

API を有効にする

1. Compute Engine インスタンス。Compute Engine インスタンスがない場合は、Compute Engine インスタンスを作成して起動するの手順に沿って操作します。
2. gcloud のインストール。gcloud のインストールについては、gcloud CLI をインストールするをご覧ください。

Collector の権限を構成する

デフォルトでは、Compute Engine インスタンスは Compute Engine のデフォルトのサービス アカウント [e-mail] を使用します。このサービス アカウントには通常、このドキュメントで説明する指標とログの書き込みに必要な Identity and Access Management（IAM）のロールが付与されています。

• モニタリング指標の書き込み（roles/monitoring.metricWriter）
• ログ書き込み（roles/logging.logWriter）
• Cloud Trace エージェント

デフォルトの代わりにユーザー管理のサービス アカウントを使用する場合は、同じロールを割り当てる必要があります。詳しくは、サービス アカウントをご覧ください。

コレクタをインストールする

Google が構築した OpenTelemetry Collector を Compute Engine インスタンスのパッケージとしてインストールする手順は次のとおりです。

Debian と Ubuntu

1. SSH または同様のツールを使用して、VM インスタンスへのターミナル接続を開き、sudo アクセス権があることを確認します。

2. 次のコマンドを実行して、パッケージ リポジトリを設定します。

   sudo mkdir -p /etc/apt/keyrings
   sudo curl -o /etc/apt/keyrings/otelcol-google.asc https://packages.cloud.google.com/apt/doc/apt-key.gpg
   cat <<EOF | sudo tee /etc/apt/sources.list.d/otelcol-google.list
   deb [signed-by=/etc/apt/keyrings/otelcol-google.asc] https://us-apt.pkg.dev/projects/cloud-ops-agents-artifacts google-cloud-opentelemetry-collector-apt main
   EOF
   

3. パッケージ マネージャーを更新して、パッケージをインストールします。

   sudo apt update
   sudo apt install otelcol-google
   

   インストール後、Google が構築した OpenTelemetry Collector が自動的に起動します。

CentOS、RHEL、Rocky Linux

1. SSH または同様のツールを使用して、VM インスタンスへのターミナル接続を開き、sudo アクセス権があることを確認します。

2. 次のコマンドを実行して、パッケージ リポジトリを設定します。

   cat <<EOF | sudo tee /etc/yum.repos.d/otelcol-google.repo
   [otelcol-google]
   name=Google Built OpenTelemetry Collector
   baseurl=https://us-yum.pkg.dev/projects/cloud-ops-agents-artifacts/google-cloud-opentelemetry-collector-yum
   autorefresh=0
   enabled=1
   type=rpm-md
   gpgcheck=1
   repo_gpgcheck=0
   gpgkey=http://dl.google.com/linux/linux_signing_key.pub
   EOF
   

3. パッケージをインストールします。

   sudo yum install otelcol-google
   

   インストール後、Google が構築した OpenTelemetry Collector が自動的に起動します。

SLES

1. SSH または同様のツールを使用して、VM インスタンスへのターミナル接続を開き、sudo アクセス権があることを確認します。

2. 次のコマンドを実行して、パッケージ リポジトリを設定します。

   cat <<EOF | sudo tee /etc/zypp/repos.d/otelcol-google.repo
   [otelcol-google]
   name=Google Built OpenTelemetry Collector
   baseurl=https://us-yum.pkg.dev/projects/cloud-ops-agents-artifacts/google-cloud-opentelemetry-collector-yum
   autorefresh=0
   enabled=1
   type=rpm-md
   gpgkey=http://dl.google.com/linux/linux_signing_key.pub
   EOF
   

3. パッケージをインストールします。

   sudo zypper install otelcol-google
   

   インストール後、Google が構築した OpenTelemetry Collector が自動的に起動します。

Windows

1. RDP または同様のツールを使用してインスタンスに接続し、Windows にログインします。

2. PowerShell アイコンを右クリックし、[管理者として実行] を選択して、管理者権限で PowerShell ターミナルを開きます。

3. 次の PowerShell コマンドを実行して、パッケージ リポジトリを設定します。

   googet addrepo otelcol-google `
       https://us-googet.pkg.dev/projects/cloud-ops-agents-artifacts/repos/google-cloud-opentelemetry-collector-googet
   

4. パッケージをインストールします。

   googet install otelcol-google
   

   インストール後、Google が構築した OpenTelemetry Collector が自動的に起動します。

Collector をデプロイする

Google が構築した OpenTelemetry Collector には、デフォルトでテレメトリーをエクスポートしない最小限の構成が含まれています。テレメトリーをエクスポートするには、コレクタをインストールした後、デフォルトの構成をオーバーライドしてコレクタを構成します。Collector の構成を次のファイルに配置します。

• Linux の場合: /etc/otelcol-google/config.yaml
• Windows の場合: C:\Program Files\Google\OpenTelemetry Collector\config.yaml

Collector を構成する

Google が構築した Collector で使用できる OpenTelemetry Collector 構成が用意されています。この構成は、大量の OTLP の指標、ログ、トレースを送信するように設計されています。この構成は、一般的な取り込みの問題を回避するようにも設計されています。構成に追加することはできますが、要素を削除しないことを強くおすすめします。

このセクションでは、用意されている構成、エクスポータ、プロセッサ、レシーバーなどの主要コンポーネント、および利用可能なその他のコンポーネントについて説明します。

用意されている Collector の構成

Collector の構成は、opentelemetry-operations-collector リポジトリの google-built-opentelemetry-collector ディレクトリにあります。

receivers:
  # Open two OTLP servers:
  # - On port 4317, open an OTLP GRPC server
  # - On port 4318, open an OTLP HTTP server
  #
  # Docs:
  # https://github.com/open-telemetry/opentelemetry-collector/tree/main/receiver/otlpreceiver
  otlp:
    protocols:
      grpc:
        endpoint: localhost:4317
      http:
        cors:
          # This effectively allows any origin
          # to make requests to the HTTP server.
          allowed_origins:
          - http://*
          - https://*
        endpoint: localhost:4318

processors:
  # The batch processor is in place to regulate both the number of requests
  # being made and the size of those requests.
  #
  # Docs:
  # https://github.com/open-telemetry/opentelemetry-collector/tree/main/processor/batchprocessor
  batch:
    send_batch_max_size: 200
    send_batch_size: 200
    timeout: 5s

  # The memorylimiter will check the memory usage of the collector process.
  #
  # Docs:
  # https://github.com/open-telemetry/opentelemetry-collector/tree/main/processor/memorylimiterprocessor
  memory_limiter:
    check_interval: 1s
    limit_percentage: 65
    spike_limit_percentage: 20

  # The resourcedetection processor is configured to detect GCP resources.
  # Resource attributes that represent the GCP resource the collector is
  # running on will be attached to all telemetry that goes through this
  # processor.
  #
  # Docs:
  # https://github.com/open-telemetry/opentelemetry-collector-contrib/tree/main/processor/resourcedetectionprocessor
  # https://github.com/open-telemetry/opentelemetry-collector-contrib/tree/main/processor/resourcedetectionprocessor#gcp-metadata
  resourcedetection:
    detectors: [gcp]
    timeout: 10s

  transform/collision:
    metric_statements:
    - context: datapoint
      statements:
      - set(attributes["exported_location"], attributes["location"])
      - delete_key(attributes, "location")
      - set(attributes["exported_cluster"], attributes["cluster"])
      - delete_key(attributes, "cluster")
      - set(attributes["exported_namespace"], attributes["namespace"])
      - delete_key(attributes, "namespace")
      - set(attributes["exported_job"], attributes["job"])
      - delete_key(attributes, "job")
      - set(attributes["exported_instance"], attributes["instance"])
      - delete_key(attributes, "instance")
      - set(attributes["exported_project_id"], attributes["project_id"])
      - delete_key(attributes, "project_id")

exporters:
  # The googlecloud exporter will export telemetry to different
  # Google Cloud services:
  # Logs -> Cloud Logging
  # Metrics -> Cloud Monitoring
  # Traces -> Cloud Trace
  #
  # Docs:
  # https://github.com/open-telemetry/opentelemetry-collector-contrib/tree/main/exporter/googlecloudexporter
  googlecloud:
    log:
      default_log_name: opentelemetry-collector

  # The googlemanagedprometheus exporter will send metrics to
  # Google Managed Service for Prometheus.
  #
  # Docs:
  # https://github.com/open-telemetry/opentelemetry-collector-contrib/tree/main/exporter/googlemanagedprometheusexporter
  googlemanagedprometheus:

extensions:
  # Opens an endpoint on 13133 that can be used to check the
  # status of the collector. Since this does not configure the
  # `path` config value, the endpoint will default to `/`.
  #
  # When running on Cloud Run, this extension is required and not optional.
  # In other environments it is recommended but may not be required for operation
  # (i.e. in Container-Optimized OS or other GCE environments).
  #
  # Docs:
  # https://github.com/open-telemetry/opentelemetry-collector-contrib/tree/main/extension/healthcheckextension
  health_check:
    endpoint: 0.0.0.0:13133

service:
  extensions:
  - health_check
  pipelines:
    logs:
      receivers:
      - otlp
      processors:
      - resourcedetection
      - memory_limiter
      - batch
      exporters:
      - googlecloud
    metrics/otlp:
      receivers:
      - otlp
      processors:
      - resourcedetection
      - transform/collision
      - memory_limiter
      - batch
      exporters:
      - googlemanagedprometheus
    traces:
      receivers:
      - otlp
      processors:
      - resourcedetection
      - memory_limiter
      - batch
      exporters:
      - googlecloud
  # Internal telemetry for the collector supports both push and pull-based telemetry data transmission.
  # Leveraging the pre-configured OTLP receiver eliminates the need for an additional port.
  #
  # Docs:
  # https://opentelemetry.io/docs/collector/internal-telemetry/
  telemetry:
    metrics:
      readers:
        - periodic:
            exporter:
              otlp:
                protocol: grpc
                endpoint: http://localhost:4317
                insecure: true

エクスポータ

Collector の構成には、次のエクスポータが含まれています。

• googlecloud エクスポータ（ログとトレース用）。このエクスポータは、デフォルトのログ名で構成されています。

• googlemanagedprometheus エクスポータ（指標用）。このエクスポータには構成は必要ありませんが、構成オプションがあります。googlemanagedprometheus エクスポータの構成オプションについては、Google Cloud Managed Service for Prometheus ドキュメントの OpenTelemetry Collector を使ってみるをご覧ください。

プロセッサ

Collector の構成には、次のプロセッサが含まれています。

• batch: テレメトリー リクエストを、 Google Cloud のリクエストあたりの最大エントリ数に達した時点か、 Google Cloud の 5 秒ごとの最小間隔のいずれか早いほうでバッチ処理するように構成します。

• memory_limiter: Collector のメモリ使用量を制限し、上限を超えたときにデータポイントを破棄することで、メモリ不足によるクラッシュを防止します。

• resourcedetection: project_id などの Google Cloud リソースラベルを自動的に検出します。

レシーバー

Collector の構成には、otlp レシーバーのみが含まれています。アプリケーションを計測して OTLP のトレースと指標を Collector の OTLP エンドポイントに送信することについては、計測方法を選択するをご覧ください。

使用可能なコンポーネント

Google が構築した OpenTelemetry Collector には、Google Cloud Observability 内でリッチなエクスペリエンスを実現するためにほとんどのユーザーが必要とするコンポーネントが含まれています。使用可能なコンポーネントの全一覧については、opentelemetry-operations-collector リポジトリのコンポーネントをご覧ください。

使用可能なコンポーネントの変更または追加をリクエストするには、opentelemetry-operations-collector リポジトリで機能リクエストを開きます。

テレメトリーを生成する

オープンソースの telemetrygen ツールを使用して構成をテストできます。ツールのダウンロードと実行の手順は、リンク先に記載されています。このツールを実行するには、Go または Docker のいずれかをインストールする必要があります。

数分後、アプリケーションによって生成されたテレメトリーが、シグナルごとに Collector を介して Google Cloud コンソールに転送され始めます。

テレメトリーを表示する

Google が構築した OpenTelemetry Collector は、計測対象のアプリケーションから Google Cloud Observability に指標、ログ、トレースを送信します。Collector は自己オブザーバビリティ指標も送信します。以下の各セクションでは、このテレメトリーを表示する方法について説明します。

指標を表示する

Google が構築した OpenTelemetry Collector は、Metrics Explorer を使用して表示できる Prometheus 指標を収集します。収集される指標はアプリの計測によって異なりますが、Google が構築した Collector も一部のセルフ指標を書き込みます。

Google が構築した OpenTelemetry Collector によって収集された指標を表示する手順は次のとおりです。

1. Google Cloud コンソールで [Metrics explorer] のページに移動します。

   [Metrics Explorer] に移動

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

2. Google Cloud コンソールのツールバーで、 Google Cloud プロジェクトを選択します。App Hub の構成には、App Hub ホスト プロジェクトまたはアプリ対応フォルダの管理プロジェクトを選択します。
3. [指標] 要素の [指標を選択] メニューを開いてフィルタバーに「Prometheus Target」と入力し、サブメニューを使用して特定のリソースタイプと指標を選択します。
   1. [有効なリソース] メニューで、[Prometheus Target] を選択します。
   2. 指標を選択するには、[有効な指標カテゴリ] メニューと [有効な指標] メニューを使用します。Google が構築した OpenTelemetry Collector によって収集された指標には、接頭辞 prometheus.googleapis.com が設定されています。
   3. [適用] をクリックします。

4. クエリ結果から時系列を削除するフィルタを追加するには、[フィルタ] 要素を使用します。

5. データの表示方法を構成します。
   

   指標の測定値が累積されている場合、Metrics Explorer によりアライメント期間ごとに測定データが自動的に正規化され、その結果、グラフに率が表示されます。詳細については、種類、タイプ、変換をご覧ください。

   counter 指標など、integer 値または double 値が測定されると、Metrics Explorer によりすべての時系列が自動的に合計されます。この動作を変更するには、[集計] エントリの最初のメニューを [なし] に設定します。

   グラフの構成の詳細については、Metrics Explorer 使用時の指標の選択をご覧ください。

トレースを表示する

トレースデータを表示するには、次の操作を行います。

1. Google Cloud コンソールで、 [Trace エクスプローラ] ページに移動します。

   [Trace エクスプローラ] に移動

   このページは、検索バーを使用して見つけることもできます。

2. Google Cloud コンソールのツールバーで、 Google Cloud プロジェクトを選択します。App Hub の構成には、App Hub ホスト プロジェクトまたは管理プロジェクトを選択します。
3. ページの表セクションで、行を選択します。

4. [トレースの詳細] パネルのガントチャートで、スパンを選択します。

   パネルが開き、トレースされたリクエストに関する情報が表示されます。詳細には、メソッド、ステータス コード、バイト数、呼び出し元のユーザー エージェントが含まれます。

5. このトレースに関連付けられているログを表示するには、[ログとイベント] タブを選択します。

   このタブには、個々のログが表示されます。ログエントリの詳細を表示するには、ログエントリを開きます。[ログを表示] をクリックし、ログ エクスプローラを使用してログを表示することもできます。

Cloud Trace エクスプローラの使用方法について詳しくは、トレースを検索して調査するをご覧ください。

ログを表示する

ログ エクスプローラではログを調査できます。また、関連するトレース（存在する場合）を確認することもできます。

1. Google Cloud コンソールで、セグメント [ログ エクスプローラ] ページに移動します。

   [ログ エクスプローラ] に移動

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

2. 計測対象のアプリのログエントリを見つけます。詳細を表示するには、ログエントリを開きます。

3. トレース メッセージを含むログエントリの [トレース] をクリックし、[トレースの詳細を表示] を選択します。

   [トレースの詳細] パネルが開き、選択したトレースが表示されます。

ログ エクスプローラの使用方法については、ログ エクスプローラを使用してログを表示するをご覧ください。

Collector のモニタリングとデバッグ

Google が構築した OpenTelemetry Collector は、パフォーマンスのモニタリングと、OTLP 取り込みパイプラインの継続的な稼働時間の確保に役立つセルフ オブザーバビリティ指標を自動的に提示します。

Collector をモニタリングするには、Collector のサンプル ダッシュボードをインストールします。このダッシュボードでは、稼働時間、メモリ使用量、Google Cloud Observability に対する API 呼び出しなど、Collector のさまざまな指標に関する分析情報を一目で確認できます。

ダッシュボードのインストール手順は次のとおりです。

1. Google Cloud コンソールで [ ダッシュボード] ページに移動します。

   [ダッシュボード] に移動

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

2. [ダッシュボード テンプレート] をクリックします。
3. OpenTelemetry Collector ダッシュボードを検索します。
4. 省略可: ダッシュボードをプレビューするには、ダッシュボードを選択します。

5. [ ダッシュボードをリストに追加] をクリックし、ダイアログを完了します。

   このダイアログでは、ダッシュボードの名前を選択し、ダッシュボードにラベルを追加できます。

ダッシュボードのインストールの詳細については、ダッシュボード テンプレートをインストールするをご覧ください。