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

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

始める前に

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

  • Cloud Monitoring API、Cloud Trace API、Cloud Logging API が有効になっている Google Cloud プロジェクト。

    • Google Cloud プロジェクトが存在しない場合は、次の操作を行います。

      1. Google Cloud コンソールで、[新しいプロジェクト] に移動します。

        新しいプロジェクトを作成

      2. [プロジェクト名] フィールドにプロジェクトの名前を入力して、[作成] をクリックします。

      3. [お支払い] に移動します。

        [お支払い] に移動

      4. 作成したプロジェクトをまだ選択していない場合は、ページ上部でプロジェクトを選択します。

      5. 既存のお支払いプロファイルを選択するか、新しいお支払いプロファイルを作成するように求められます。

      新しいプロジェクトでは、Monitoring API、Trace API、Logging API がデフォルトで有効になっています。

    • Google Cloud プロジェクトがすでに存在する場合は、Monitoring API、Trace API、Logging API が有効になっていることを確認します。

      Enable the APIs

  • Kubernetes クラスタ。Kubernetes クラスタがない場合は、GKE のクイックスタートの説明に従います。

  • 次のコマンドライン ツール:

    • gcloud
    • kubectl

    gcloud ツールと kubectl ツールは Google Cloud CLI に含まれています。インストールの詳細については、Google Cloud CLI コンポーネントの管理をご覧ください。インストールされている gcloud CLI コンポーネントを確認するには、次のコマンドを実行します。

    gcloud components list
    

Collector の権限を構成する

GKE Workload Identity を無効にしている場合、このセクションはスキップしてください。

テレメトリーをエクスポートするために必要な権限が OpenTelemetry Collector の Kubernetes サービス アカウントに付与されていることを確認するには、プロジェクトに対する次の IAM ロールを OpenTelemetry Collector の Kubernetes サービス アカウントに付与するよう管理者に依頼してください。

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

管理者は、カスタムロールや他の事前定義ロールを使用して、OpenTelemetry Collector の Kubernetes サービス アカウントに必要な権限を付与することもできます。

権限を構成するには、次の add-iam-policy-binding コマンドを使用します。

gcloud projects add-iam-policy-binding projects/PROJECT_ID \
    --role=roles/logging.logWriter \
    --member=principal://iam.googleapis.com/projects/PROJECT_NUMBER/locations/global/workloadIdentityPools/PROJECT_ID.svc.id.goog/subject/ns/opentelemetry/sa/opentelemetry-collector
gcloud projects add-iam-policy-binding projects/PROJECT_ID \
    --role=roles/monitoring.metricWriter \
    --member=principal://iam.googleapis.com/projects/PROJECT_NUMBER/locations/global/workloadIdentityPools/PROJECT_ID.svc.id.goog/subject/ns/opentelemetry/sa/opentelemetry-collector
gcloud projects add-iam-policy-binding projects/PROJECT_ID \
    --role=roles/cloudtrace.agent \
    --member=principal://iam.googleapis.com/projects/PROJECT_NUMBER/locations/global/workloadIdentityPools/PROJECT_ID.svc.id.goog/subject/ns/opentelemetry/sa/opentelemetry-collector

コマンドを実行する前に、次の変数を置き換えます。

  • PROJECT_ID: プロジェクトの ID。
  • PROJECT_NUMBER: Google Cloud プロジェクト番号。

Collector をデプロイする

Collector パイプラインは、セルフマネージド OTLP Kubernetes の取り込み用のリポジトリで提供されている検証済みのサンプルから直接デプロイできます。PROJECT_ID を Google Cloud プロジェクトの ID に置き換えてから、次のコマンドを使用して GitHub から直接デプロイできます。

export GOOGLE_CLOUD_PROJECT=PROJECT_ID
export PROJECT_NUMBER=PROJECT_NUMBER
kubectl kustomize https://github.com/GoogleCloudPlatform/otlp-k8s-ingest.git/k8s/base | envsubst | kubectl apply -f -

コマンドを実行する前に、次の変数を置き換えます。

  • PROJECT_ID: プロジェクトの ID。
  • PROJECT_NUMBER: プロジェクトの数値 ID。

Collector を構成する

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

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

用意されている Collector の構成

Kubernetes 環境の Collector の構成は、otlp-k8s-ingest リポジトリにあります。

# Copyright 2024 Google LLC
#
# Licensed under the Apache License, Version 2.0 (the "License");
# you may not use this file except in compliance with the License.
# You may obtain a copy of the License at
#
#     http://www.apache.org/licenses/LICENSE-2.0
#
# Unless required by applicable law or agreed to in writing, software
# distributed under the License is distributed on an "AS IS" BASIS,
# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
# See the License for the specific language governing permissions and
# limitations under the License.

exporters:
  googlecloud:
    log:
      default_log_name: opentelemetry-collector
    user_agent: Google-Cloud-OTLP manifests:0.3.0 OpenTelemetry Collector Built By Google/0.128.0 (linux/amd64)
  googlemanagedprometheus:
    user_agent: Google-Cloud-OTLP manifests:0.3.0 OpenTelemetry Collector Built By Google/0.128.0 (linux/amd64)
  # The otlphttp exporter is used to send traces to Google Cloud Trace using OTLP http/proto
  # The otlp exporter could also be used to send them using OTLP grpc
  otlphttp:
    encoding: proto
    endpoint: https://telemetry.googleapis.com
    # Use the googleclientauth extension to authenticate with Google credentials
    auth:
      authenticator: googleclientauth


extensions:
  health_check:
    endpoint: ${env:MY_POD_IP}:13133
  googleclientauth:


processors:
  filter/self-metrics:
    metrics:
      include:
        match_type: strict
        metric_names:
        - otelcol_process_uptime
        - otelcol_process_memory_rss
        - otelcol_grpc_io_client_completed_rpcs
        - otelcol_googlecloudmonitoring_point_count
  batch:
    send_batch_max_size: 200
    send_batch_size: 200
    timeout: 5s

  k8sattributes:
    extract:
      metadata:
      - k8s.namespace.name
      - k8s.deployment.name
      - k8s.statefulset.name
      - k8s.daemonset.name
      - k8s.cronjob.name
      - k8s.job.name
      - k8s.replicaset.name
      - k8s.node.name
      - k8s.pod.name
      - k8s.pod.uid
      - k8s.pod.start_time
    passthrough: false
    pod_association:
    - sources:
      - from: resource_attribute
        name: k8s.pod.ip
    - sources:
      - from: resource_attribute
        name: k8s.pod.uid
    - sources:
      - from: connection

  memory_limiter:
    check_interval: 1s
    limit_percentage: 65
    spike_limit_percentage: 20

  metricstransform/self-metrics:
    transforms:
    - action: update
      include: otelcol_process_uptime
      operations:
      - action: add_label
        new_label: version
        new_value: Google-Cloud-OTLP manifests:0.3.0 OpenTelemetry Collector Built By Google/0.128.0 (linux/amd64)

  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")

  # The relative ordering of statements between ReplicaSet & Deployment and Job & CronJob are important.
  # The ordering of these controllers is decided based on the k8s controller documentation available at
  # https://kubernetes.io/docs/concepts/workloads/controllers.
  # The relative ordering of the other controllers in this list is inconsequential since they directly
  # create pods.
  transform/aco-gke:
    metric_statements:
    - context: datapoint
      statements:
      - set(attributes["top_level_controller_type"], "ReplicaSet") where resource.attributes["k8s.replicaset.name"] != nil
      - set(attributes["top_level_controller_name"], resource.attributes["k8s.replicaset.name"]) where resource.attributes["k8s.replicaset.name"] != nil
      - set(attributes["top_level_controller_type"], "Deployment") where resource.attributes["k8s.deployment.name"] != nil
      - set(attributes["top_level_controller_name"], resource.attributes["k8s.deployment.name"]) where resource.attributes["k8s.deployment.name"] != nil
      - set(attributes["top_level_controller_type"], "DaemonSet") where resource.attributes["k8s.daemonset.name"] != nil
      - set(attributes["top_level_controller_name"], resource.attributes["k8s.daemonset.name"]) where resource.attributes["k8s.daemonset.name"] != nil
      - set(attributes["top_level_controller_type"], "StatefulSet") where resource.attributes["k8s.statefulset.name"] != nil
      - set(attributes["top_level_controller_name"], resource.attributes["k8s.statefulset.name"]) where resource.attributes["k8s.statefulset.name"] != nil
      - set(attributes["top_level_controller_type"], "Job") where resource.attributes["k8s.job.name"] != nil
      - set(attributes["top_level_controller_name"], resource.attributes["k8s.job.name"]) where resource.attributes["k8s.job.name"] != nil
      - set(attributes["top_level_controller_type"], "CronJob") where resource.attributes["k8s.cronjob.name"] != nil
      - set(attributes["top_level_controller_name"], resource.attributes["k8s.cronjob.name"]) where resource.attributes["k8s.cronjob.name"] != nil

  # When sending telemetry to the GCP OTLP endpoint, the gcp.project_id resource attribute is required to be set to your project ID.
  resource/gcp_project_id:
    attributes:
    - key: gcp.project_id
      # MAKE SURE YOU REPLACE THIS WITH YOUR PROJECT ID
      value: ${GOOGLE_CLOUD_PROJECT}
      action: insert
  # The metricstarttime processor is important to include if you are using the prometheus receiver to ensure the start time is set properly.
  # It is a no-op otherwise.
  metricstarttime:
    strategy: subtract_initial_point

receivers:
  # This collector is configured to accept OTLP metrics, logs, and traces, and is designed to receive OTLP from workloads running in the cluster.
  otlp:
    protocols:
      grpc:
        endpoint: ${env:MY_POD_IP}:4317
      http:
        cors:
          allowed_origins:
          - http://*
          - https://*
        endpoint: ${env:MY_POD_IP}:4318
  otlp/self-metrics:
    protocols:
      grpc:
        endpoint: ${env:MY_POD_IP}:14317

service:
  extensions:
  - health_check
  - googleclientauth
  pipelines:
    logs:
      exporters:
      - googlecloud
      processors:
      - k8sattributes
      - resourcedetection
      - memory_limiter
      - batch
      receivers:
      - otlp
    metrics/otlp:
      exporters:
      - googlemanagedprometheus
      processors:
      - k8sattributes
      - memory_limiter
      - metricstarttime
      - resourcedetection
      - transform/collision
      - transform/aco-gke
      - batch
      receivers:
      - otlp
    metrics/self-metrics:
      exporters:
      - googlemanagedprometheus
      processors:
      - filter/self-metrics
      - metricstransform/self-metrics
      - k8sattributes
      - memory_limiter
      - resourcedetection
      - batch
      receivers:
      - otlp/self-metrics
    traces:
      exporters:
      - otlphttp
      processors:
      - k8sattributes
      - memory_limiter
      - resource/gcp_project_id
      - resourcedetection
      - batch
      receivers:
      - otlp
  telemetry:
    logs:
      encoding: json
    metrics:
      readers:
      - periodic:
          exporter:
            otlp:
              protocol: grpc
              endpoint: ${env:MY_POD_IP}:14317

エクスポータ

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

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

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

プロセッサ

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

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

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

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

  • k8sattributes: Kubernetes リソース属性をテレメトリー ラベルに自動的にマッピングします。

  • transform: Google Cloudモニタリング対象リソースのラベルと競合する指標ラベルの名前を変更します。

レシーバー

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

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

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

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

テレメトリーを生成する

このセクションでは、サンプル アプリケーションをデプロイし、そのアプリケーションが Collector の OTLP エンドポイントを参照するように設定して、Google Cloudでテレメトリーを表示する方法について説明します。サンプル アプリケーションは、トレース、ログ、指標を Collector にエクスポートする小さな生成ツールです。

OpenTelemetry SDK で計測されたアプリケーションがすでにある場合は、代わりに Collector のエンドポイントを参照するようにアプリケーションを設定できます。

サンプル アプリケーションをデプロイするには、次のコマンドを実行します。

kubectl apply -f https://raw.githubusercontent.com/GoogleCloudPlatform/otlp-k8s-ingest/main/sample/app.yaml

OpenTelemetry SDK を使用する既存のアプリケーションが Collector のエンドポイントを参照するようにするには、OTEL_EXPORTER_OTLP_ENDPOINT 環境変数を http://opentelemetry-collector.opentelemetry.svc.cluster.local:4317 に設定します。

数分後、アプリケーションによって生成されたテレメトリーが、シグナルごとに 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. データの表示方法を構成します。

    指標の測定値が累積されている場合、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. [ ダッシュボードをリストに追加] をクリックし、ダイアログを完了します。

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

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