Google Kubernetes Engine に OpenTelemetry Collector をデプロイする

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

始める前に

GKE で 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 が有効になっていることを確認します。

    1. [API とサービス] に移動します。

       [API とサービス] に移動

    2. プロジェクトを選択します。

    3. [ API とサービスの有効化] をクリックします。

    4. 各 API を名前で検索します。

    5. 検索結果で API の名前をクリックします。Monitoring API は「Stackdriver Monitoring API」と表示されます。

    6. [API が有効です] と表示されていない場合は、[有効にする] をクリックします。

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

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

  • gcloud
  • kubectl

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

  gcloud components list
  

Collector をデプロイする

Collector パイプラインは、次のコマンドを使用して GitHub から直接デプロイできます。PROJECT_ID は、Google Cloud プロジェクトの ID に置き換えます。

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

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

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

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

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

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

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

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

2. [サンプル ライブラリ] タブを選択します。
3. カテゴリで [OpenTelemetry Collector] を選択します。
4. [OpenTelemtry Collector] を選択します。
5. [インポート] をクリックします。

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

Collector を構成する

セルフマネージド OTLP 取り込みパイプラインには、デフォルトの OpenTelemetry コレクタ構成が含まれています。この構成は、大量の OTLP 指標、ログ、トレースを送信し、一貫した GKE と Kubernetes のメタデータを付加するように設計されています。また、一般的な取り込みの問題を防ぐように設計されています。

ただし、ニーズによってはデフォルト構成のカスタマイズが必要になる場合があります。このセクションでは、パイプラインのデフォルトと、ニーズに合わせてデフォルトをカスタマイズする方法について説明します。

デフォルトのコレクタ構成は、GitHub の config/collector.yaml にあります。

# 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.1.0 otel/opentelemetry-collector-contrib:0.106.0
  googlemanagedprometheus:
    user_agent: Google-Cloud-OTLP manifests:0.1.0 otel/opentelemetry-collector-contrib:0.106.0

extensions:
  health_check:
    endpoint: ${env:MY_POD_IP}:13133
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.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.1.0 otel/opentelemetry-collector-contrib:0.106.0

  # We need to add the pod IP as a resource label so the k8s attributes processor can find it.
  resource/self-metrics:
    attributes:
    - action: insert
      key: k8s.pod.ip
      value: ${env:MY_POD_IP}

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

receivers:
  otlp:
    protocols:
      grpc:
        endpoint: ${env:MY_POD_IP}:4317
      http:
        cors:
          allowed_origins:
          - http://*
          - https://*
        endpoint: ${env:MY_POD_IP}:4318
  prometheus/self-metrics:
    config:
      scrape_configs:
      - job_name: otel-self-metrics
        scrape_interval: 1m
        static_configs:
        - targets:
          - ${env:MY_POD_IP}:8888

service:
  extensions:
  - health_check
  pipelines:
    logs:
      exporters:
      - googlecloud
      processors:
      - k8sattributes
      - resourcedetection
      - memory_limiter
      - batch
      receivers:
      - otlp
    metrics/otlp:
      exporters:
      - googlemanagedprometheus
      processors:
      - k8sattributes
      - memory_limiter
      - resourcedetection
      - transform/collision
      - batch
      receivers:
      - otlp
    metrics/self-metrics:
      exporters:
      - googlemanagedprometheus
      processors:
      - filter/self-metrics
      - metricstransform/self-metrics
      - resource/self-metrics
      - k8sattributes
      - memory_limiter
      - resourcedetection
      - batch
      receivers:
      - prometheus/self-metrics
    traces:
      exporters:
      - googlecloud
      processors:
      - k8sattributes
      - memory_limiter
      - resourcedetection
      - batch
      receivers:
      - otlp
  telemetry:
    metrics:
      address: ${env:MY_POD_IP}:8888

エクスポーター

デフォルトのエクスポーターには、googlecloud エクスポーター（ログとトレースを対象）と googlemanagedprometheus エクスポーター（指標を対象）があります。

googlecloud エクスポーターは、デフォルトのログ名で構成されています。googlemanagedprometheus エクスポーターにはデフォルトの構成は必要ありません。このエクスポーターの構成の詳細については、Google Cloud Managed Service for Prometheus ドキュメントの OpenTelemetry コレクタを使ってみるをご覧ください。

プロセッサ

デフォルト構成には、次のプロセッサが含まれています。

• batch: Google Cloud のリクエストあたりの最大エントリ数に達した時点か、Google Cloud の最小間隔（5 秒）のいずれか早いほうで、テレメトリー リクエストをバッチ処理するように構成します。
• k8sattributes: Kubernetes リソース属性をテレメトリー ラベルに自動的にマッピングします。
• memory_limiter: Collector のメモリ使用量を適切なレベルで制限します。このレベルを超えるデータポイントを破棄することで、メモリ不足によるクラッシュを防ぎます。
• resourcedetection: クラスタ名やプロジェクト ID などの Google Cloud リソースラベルを自動的に検出します。
• transform: Google Cloud のモニタリング対象リソース フィールドと競合する指標ラベルの名前を変更します。

レシーバー

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

次のステップ: テレメトリーを収集して表示する

このセクションでは、サンプル アプリケーションをデプロイし、そのアプリケーションが 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 コンソールに転送され始めます。