Google uses AI technology to translate content into your preferred language. AI translations can contain errors.

GKE 用マネージド OpenTelemetry をデプロイする

Autopilot Standard

このドキュメントでは、GKE で実行されているアプリケーションから OpenTelemetry Protocol（OTLP）のトレース、指標、ログを Google Cloud Observability に送信するように Managed OpenTelemetry for GKE を設定する方法について説明します。

GKE 用マネージド OpenTelemetry の仕組みの詳細については、GKE 用マネージド OpenTelemetry をご覧ください。

GKE 用マネージド OpenTelemetry を使用すると、次のことができます。

OpenTelemetry Protocol（OTLP）のトレース、指標、ログをマネージドコレクタに送信するように、GKE で実行されているワークロードを構成します。
GKE で実行されているアプリケーションから OpenTelemetry Protocol（OTLP）のトレース、指標、ログを受信します。
そのデータを Google Cloud Observability にエクスポートします。

コレクタレベルのフィルタリングと制御が必要な場合は、このマネージドサービスではなく、Google が構築した OpenTelemetry Collector を使用します。

始める前に

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

Google Cloud CLI をインストールします。

注: すでに gcloud CLI をインストールしている場合は、gcloud components update を実行して、最新バージョンがインストールされていることを確認してください。

外部 ID プロバイダ（IdP）を使用している場合は、まず連携 ID を使用して gcloud CLI にログインする必要があります。

gcloud CLI を初期化するには、次のコマンドを実行します。

gcloud init

Google Cloud プロジェクトを作成または選択します。

プロジェクトの選択または作成に必要なロール

プロジェクトを選択する: プロジェクトの選択に特定の IAM ロールは必要ありません。ロールが付与されているプロジェクトであれば、どのプロジェクトでも選択できます。
プロジェクトを作成する: プロジェクトを作成するには、resourcemanager.projects.create 権限を含むプロジェクト作成者ロール（roles/resourcemanager.projectCreator）が必要です。詳しくは、ロールを付与する方法をご覧ください。

Google Cloud プロジェクトを作成します。
```
gcloud projects create PROJECT_ID
```
PROJECT_ID は、作成する Google Cloud プロジェクトの名前に置き換えます。
作成した Google Cloud プロジェクトを選択します。
```
gcloud config set project PROJECT_ID
```
PROJECT_ID は、 Google Cloud プロジェクトの名前に置き換えます。

このガイドを完了するために必要な権限があることを確認します。

Google Cloud プロジェクトに対して課金が有効になっていることを確認します。

GKE、Telemetry（OTLP）、Cloud Logging、Cloud Monitoring、Cloud Trace の各 API を有効にします。

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

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

gcloud services enable container.googleapis.com telemetry.googleapis.com logging.googleapis.com monitoring.googleapis.com cloudtrace.googleapis.com

Google Cloud CLI をインストールします。

外部 ID プロバイダ（IdP）を使用している場合は、まず連携 ID を使用して gcloud CLI にログインする必要があります。

gcloud CLI を初期化するには、次のコマンドを実行します。

gcloud init

Google Cloud プロジェクトを作成または選択します。

プロジェクトの選択または作成に必要なロール

プロジェクトを選択する: プロジェクトの選択に特定の IAM ロールは必要ありません。ロールが付与されているプロジェクトであれば、どのプロジェクトでも選択できます。
プロジェクトを作成する: プロジェクトを作成するには、resourcemanager.projects.create 権限を含むプロジェクト作成者ロール（roles/resourcemanager.projectCreator）が必要です。詳しくは、ロールを付与する方法をご覧ください。

Google Cloud プロジェクトを作成します。
```
gcloud projects create PROJECT_ID
```
PROJECT_ID は、作成する Google Cloud プロジェクトの名前に置き換えます。
作成した Google Cloud プロジェクトを選択します。
```
gcloud config set project PROJECT_ID
```
PROJECT_ID は、 Google Cloud プロジェクトの名前に置き換えます。

このガイドを完了するために必要な権限があることを確認します。

Google Cloud プロジェクトに対して課金が有効になっていることを確認します。

GKE、Telemetry（OTLP）、Cloud Logging、Cloud Monitoring、Cloud Trace の各 API を有効にします。

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

gcloud services enable container.googleapis.com telemetry.googleapis.com logging.googleapis.com monitoring.googleapis.com cloudtrace.googleapis.com

要件

Managed OpenTelemetry for GKE を使用するには、次の要件を満たす必要があります。

クラスタに GKE バージョン 1.34.1-gke.2178000 以降が必要です。
バージョン 551.0.0 以降で有効になっている gcloud CLI。
Terraform を使用して GKE インフラストラクチャをプロビジョニングする場合は、バージョン v7.17.0 以降の terraform-provider-google-beta プロバイダを使用する必要があります。

必要なロール

GKE マネージド OpenTelemetry を有効にして使用するために必要な権限を取得するには、プロジェクトに対する次の IAM ロールを付与するよう管理者に依頼してください。

Kubernetes Engine クラスタ管理者（roles/container.clusterAdmin）
モニタリング閲覧者（roles/monitoring.viewer）
ログビューア（roles/logging.viewer）
Cloud トレースユーザー（roles/cloudtrace.user）

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

必要な権限は、カスタムロールや他の事前定義ロールから取得することもできます。

費用

Managed OpenTelemetry for GKE の使用に関連する費用の詳細については、課金をご覧ください。

クラスタで GKE 用マネージド OpenTelemetry を有効にする

GKE 用マネージド OpenTelemetry を設定するには、次の操作を行う必要があります。

クラスタで GKE 用マネージド OpenTelemetry を有効にします。
モニタリングするアプリケーションを構成して、マネージドコレクタのエンドポイントにシグナルを送信します。

GKE 用マネージド OpenTelemetry を有効にすると、次のオブジェクトがクラスタにデプロイされます。

gke-managed-otel Namespace 内にデプロイされる GKE Managed OpenTelemetry Collector デプロイ。ログ、指標、トレース用のクラスタ内マネージド OpenTelemetry Collector HTTP エンドポイントは http://opentelemetry-collector.gke-managed-otel.svc.cluster.local:4318 です。
ワークロードの自動構成の設定に使用できるカスタムリソース定義 instrumentations.telemetry.googleapis.com。

カスタムリソースの詳細については、Kubernetes ドキュメントのカスタムリソースをご覧ください。

新しいクラスタで有効にする

新しいクラスタで Managed OpenTelemetry for GKE を有効にするには、次の操作を行います。

gcloud

Autopilot クラスタの場合は、次のコマンドを使用します。

gcloud beta container clusters create-auto CLUSTER_NAME \
  --project=PROJECT_ID \
  --managed-otel-scope=COLLECTION_AND_INSTRUMENTATION_COMPONENTS \
  --location=LOCATION \
  --cluster-version=VERSION

次のように置き換えます。

CLUSTER_NAME: クラスタの名前。
PROJECT_ID: Google Cloud プロジェクト ID。
LOCATION: リージョンまたはゾーン。
VERSION: バージョン。1.34.1-gke.2178000 以降にする必要があります。

Standard クラスタの場合は、次のコマンドを使用します。

gcloud beta container clusters create CLUSTER_NAME \
  --project=PROJECT_ID \
  --managed-otel-scope=COLLECTION_AND_INSTRUMENTATION_COMPONENTS \
  --location=LOCATION \
  --cluster-version=VERSION

次のように置き換えます。

CLUSTER_NAME: クラスタの名前。
PROJECT_ID: Google Cloud プロジェクト ID。
LOCATION: リージョンまたはゾーン。
VERSION: バージョン。1.34.1-gke.2178000 以降にする必要があります。

コンソール

Autopilot クラスタの場合は、次の操作を行います。
1. Google Cloud コンソールで、[Autopilot クラスタの作成] ページに移動します。
  [Autopilot クラスタの作成] に移動
2. ナビゲーションパネルで [詳細設定] をクリックします。
3. [オペレーション] セクションで、[マネージド OpenTelemetry を有効にする] を選択します。
4. [保存] をクリックします。
Standard クラスタの場合は、次の操作を行います。
1. Google Cloud コンソールで、[Kubernetes クラスタの作成] ページに移動します。
  [Kubernetes クラスタの作成] に移動
2. ナビゲーションパネルで [機能] をクリックします。
3. [オペレーション] セクションで、[マネージド OpenTelemetry を有効にする] を選択します。
4. [保存] をクリックします。

Terraform

Terraform を使用して新しいクラスタで Managed OpenTelemetry for GKE を有効にするには、次の例を参照してください。

terraform {
  required_providers {
    google-beta = {
      source  = "hashicorp/google-beta"
      version = ">= 7.17.0"
    }
  }
}

resource "google_container_cluster" "default" {
  name     = "gke-standard-regional-with-managed-otel"
  provider = google-beta
  location = "us-west1"

  initial_node_count = 1
  release_channel {
    channel = "RAPID" # The default rapid version already has the feature available.
  }

  managed_opentelemetry_config {
    scope = "COLLECTION_AND_INSTRUMENTATION_COMPONENTS"
  }
}

Terraform の使用方法の詳細については、GKE での Terraform のサポートをご覧ください。

既存のクラスタで有効にする

既存のクラスタで Managed OpenTelemetry for GKE を有効にする手順は次のとおりです。

gcloud

クラスタのバージョンが 1.34.1-gke.2178000 以降であることを確認します。既存のクラスタをアップグレードする方法の詳細については、Standard クラスタのアップグレードと Autopilot クラスタのアップグレードをご覧ください。
次のコマンドを使用して、GKE 用 Managed OpenTelemetry を有効にします。
```
gcloud beta container clusters update CLUSTER_NAME \
  --project=PROJECT_ID \
  --managed-otel-scope=COLLECTION_AND_INSTRUMENTATION_COMPONENTS \
  --location=LOCATION
```
次のように置き換えます。
- CLUSTER_NAME: クラスタの名前。
- PROJECT_ID: Google Cloud プロジェクト ID。
- LOCATION: リージョンまたはゾーン。

コンソール

クラスタのバージョンが 1.34.1-gke.2178000 以降であることを確認します。既存のクラスタをアップグレードする方法の詳細については、Standard クラスタのアップグレードと Autopilot クラスタのアップグレードをご覧ください。
Google Cloud コンソールで、[Kubernetes クラスタ] ページに移動します。

Kubernetes クラスタに移動
クラスタの名前をクリックします。
[機能] リストで、[Managed OpenTelemetry] オプションを見つけます。無効と表示されている場合は、[編集] をクリックし、[マネージド OpenTelemetry を有効にする] を選択します。
[変更を保存] をクリックします。

Terraform

既存のクラスタで GKE 用 Managed OpenTelemetry を有効にするには、次の例のように、既存の google_container_cluster リソースに managed_opentelemetry_config ブロックを追加します。

terraform {
  required_providers {
    google-beta = {
      source  = "hashicorp/google-beta"
      version = ">= 7.17.0"
    }
  }
}

resource "google_container_cluster" "default" {
  name     = "gke-standard-regional-with-managed-otel"
  provider = google-beta
  location = "us-west1"

  initial_node_count = 1
  release_channel {
    channel = "RAPID" # The default rapid version already has the feature available.
  }

  managed_opentelemetry_config {
    scope = "COLLECTION_AND_INSTRUMENTATION_COMPONENTS"
  }
}

Terraform の使用方法の詳細については、GKE での Terraform のサポートをご覧ください。

マネージド OpenTelemetry コレクタを使用するようにアプリケーションを構成する

マネージドコレクタのエンドポイントにシグナルを送信できるように、アプリケーションを構成する必要があります。アプリケーションが構成されると、マネージド OpenTelemetry コレクタは、コレクタが有効になっているクラスタで実行されているアプリケーションからシグナルを受信します。アプリケーションからのシグナルには、トレース、指標、ログが含まれます。

OpenTelemetry シグナルを送信するには、OpenTelemetry 指標を生成するようにアプリケーションがすでに計測されている必要があります。詳細については、サポートされているワークロードをご覧ください。

マネージドコレクタのエンドポイントにシグナルを送信するようにアプリケーションを手動で構成することも、自動構成を使用することもできます。自動構成によって手動での変更がオーバーライドされる可能性があるため、同じワークロードで両方の方法を同時に使用することはおすすめしません。この組み合わせでは、構成の変更を追跡することが難しくなる可能性があります。

以降のセクションでは、自動構成を使用してコレクタにシグナルを送信するようにアプリケーションを構成する方法について説明します。

自動構成を設定する

自動構成では、環境変数を使用して、マネージドコレクタのエンドポイントにシグナルを送信するようにワークロードを構成します。

Pod への環境変数の自動挿入を有効にするには、Instrumentation カスタムリソースを使用します。環境変数には OpenTelemetry 構成が含まれており、Namespace 内のラベルが一致する一部の Pod または Namespace 内のすべての Pod に挿入できます。

その後、アプリケーションが Namespace にデプロイされると、GKE は構成を使用して、ワークロードが実行される Pod に環境変数を自動的に挿入します。

Instrumentation カスタムリソースを構成する手順は次のとおりです。
1. 次の Instrumentation マニフェストを otlp-auto-config-namespace.yaml という名前のファイルに保存します。
```
apiVersion: telemetry.googleapis.com/v1alpha1
kind: Instrumentation
metadata:
  namespace: NAMESPACE
  name: NAME
spec:
  selector:
    matchLabels:
      KEY: VALUE
  autoInstrumentationConfig:
    configInjection:
      enabled: true
  otelSDKConfig:
    tracer_provider:
      sampler:
        parent_based:
          root:
            trace_id_ratio_based:
              ratio: "TRACE_RATIO"
    meter_provider:
      readers:
      - periodic:
          interval: METRICS_INTERVAL
```
  次のように置き換えます。
  - NAMESPACE: 自動計測の対象とする Pod を含む Namespace。default を使用して、デフォルトの Namespace をターゲットにします。
  - NAME: マニフェストファイルの名前。この例では、名前は otlp-auto-config-namespace.yaml です。
  - （省略可）ターゲットとする Pod に関連付けられたラベル。空のセレクタ（{}）が指定されている場合、Namespace 内のすべての Pod がターゲットになります。
    - KEY: ラベルのキー。
    - VALUE: ラベルの値。
  - TRACE_RATIO: 収集するトレースデータの比率。指定しない場合、デフォルトは 1.0 です。詳細については、トレースサンプリングレートを変更するをご覧ください。
  - METRICS_INTERVAL: 収集するモニタリングデータの間隔（ミリ秒単位）。デフォルトは 30000 です。値は負でない値で、最小値は 5,000 ミリ秒、最大値は 300,000 ミリ秒、5,000 ミリ秒の倍数である必要があります。詳細については、指標のエクスポート間隔を変更するをご覧ください。
2. 設定を変更する場合は、次のセクションで構成を変更するをご覧ください。
3. 次のコマンドを実行して構成を適用します。
```
kubectl apply -f otlp-auto-config-namespace.yaml
```
環境変数を自動的に挿入するには、構成が適用されているクラスタの Namespace にアプリケーションをデプロイする必要があります。
- まだ Namespace で実行されていないワークロードに構成を適用するには、次のコマンドを使用してワークロードをデプロイします。
```
kubectl apply -f DEPLOYMENT_NAME -n NAMESPACE
```
  次のように置き換えます。
  - DEPLOYMENT_NAME: デプロイメントの名前。
  - NAMESPACE: Namespace。
- 構成を Namespace で実行中のワークロードに適用するには、次のコマンドを使用してワークロードを再デプロイします。
```
kubectl rollout restart deployment DEPLOYMENT_NAME -n NAMESPACE
```
  次のように置き換えます。
  - DEPLOYMENT_NAME: デプロイメントの名前。
  - NAMESPACE: Namespace。

構成をクラスタに適用すると、GKE はクラスタにデプロイされたときにすべてのワークロードを自動的に構成します。ワークロードは、ワークロードが実行される Pod に環境変数を挿入することで計測されます。

これらの環境変数で構成されたワークロードが、マネージドコレクタがデプロイされているクラスタで実行されている場合、ワークロードの実行時に OpenTelemetry シグナルがマネージドコレクタに送信されます。これらのシグナルは、Google Cloud Observability で確認できます。

シグナルの表示の詳細については、テレメトリーを表示するをご覧ください。例については、サンプルテレメトリーを生成するをご覧ください。

構成を変更する

構成を変更するには、次の操作を行う必要があります。

Instrumentation マニフェストファイルを変更します。
変更した構成を適用します。
変更した構成を適用したら、クラスタの対応する Namespace でアプリケーションを再デプロイまたは再起動します。

これらの手順の詳細については、構成を作成してデプロイするセクションの手順に沿って操作してください。

データの収集の量や頻度を変更する

収集されるトレースデータの量は、トレースサンプリングレートを変更することで変更できます。

モニタリングデータが Cloud Monitoring に送信される頻度は、指標のエクスポート間隔を変更することで変更できます。

収集されるロギングデータの量や頻度を変更することはできません。ただし、ロギング、指標、トレースのすべてのデータの収集を無効にすることはできます。詳しくは、収集するシグナルタイプを選択するをご覧ください。

トレースのサンプリングレートを変更する

ワークロードは大量のトレースデータを生成する可能性があります。ご自身の状況に合わせて、データの収集と保存にかかる費用と、データが有用となるために必要な詳細度のバランスを判断することが重要です。

デフォルトの OpenTelemetry SDK の動作は always_on で、比率 1 と同等です。

トレースサンプリングレートの構成例を次に示します。この例では、比率は 0.25 であるため、トレースデータは 25% のレートで収集されます。この比率の数値を変更して、サンプルレートを変更します。

    tracer_provider:
      sampler:
        parent_based:
          root:
            trace_id_ratio_based:
              ratio: "0.25"

指標のエクスポート間隔を変更する

指標のエクスポート間隔によって、Cloud Monitoring のグラフに表示されるデータの粒度が決まります。

次の例は、指標のエクスポート間隔の構成です。この例では、エクスポート間隔は 30,000 ミリ秒です。

指標エクスポート間隔は、OpenTelemetry SDK からの指標の連続する 2 つのエクスポートの開始間の遅延間隔を指定するために使用されます。

この間隔の値は 0 以上で、最小値は 5,000 ミリ秒、最大値は 300,000 ミリ秒、5,000 ミリ秒の倍数にする必要があります。値はミリ秒単位で表されます。

meter_provider:
  readers:
  - periodic:
      interval: 30000

収集するシグナルタイプを選択する

収集しないシグナルタイプを無効にすることで、ワークロードから収集するシグナルタイプを制御できます。シグナルタイプは、トレース、指標、ログです。

シグナルタイプを無効にするには、ワークロードが実行されるコンテナの環境変数を使用します。環境変数を変更するには、Instrumentation カスタムリソースを変更してから、ワークロードをコンテナに再デプロイします。

次の例は、トレースデータのみの収集用に構成された Instrumentation マニフェストファイルです。meter_provider と logger_provider が null に設定されているため、ログと指標の収集が無効になっています。

apiVersion: telemetry.googleapis.com/v1alpha1
kind: Instrumentation
metadata:
  namespace: default
  name: otlp-auto-config-disable-metrics-logs
spec:
  selector:
    matchLabels: # Update the labels to match your workloads
      app: telemetrygen-app
  autoInstrumentationConfig:
    configInjection:
      enabled: true
  otelSDKConfig:
    meter_provider: null
    logger_provider: null

マルチモーダルプロンプトとレスポンスのデータを収集する

マルチモーダルプロンプトとレスポンスのデータを収集するように、GKE 用マネージド OpenTelemetry を構成できます。

この機能は、LangGraph ReAct エージェントと、Agent Development Kit（ADK）フレームワークで構築された生成 AI エージェントで使用できます。

マルチモーダルプロンプトとレスポンスのデータを収集するように Managed OpenTelemetry for GKE を構成するには、次の操作を行います。

マルチモーダルプロンプトとレスポンスを収集するセクションの手順に沿って、 Google Cloud プロジェクトと使用する SDK を構成します。
マルチモーダルプロンプトとレスポンスの収集に使用する Cloud Storage バケットを作成または特定します。詳細については、バケットを作成するをご覧ください。
アプリケーションが使用するサービスアカウントに、Cloud Storage バケットに対する storage.objects.create 権限を付与します。

この権限により、アプリケーションは Cloud Storage バケットにオブジェクトを書き込むことができます。これらのオブジェクトには、エージェントアプリケーションが作成および受信するプロンプトとレスポンスが保存されます。詳細については、バケットでの IAM ポリシーの設定と管理をご覧ください。

Instrumentation カスタムリソースで promptsResponses.uploadBasePath フィールドを構成します。次に例を示します。

apiVersion: telemetry.googleapis.com/v1alpha1
kind: Instrumentation
metadata:
  namespace: default
  name: prompts-responses
spec:
  selector: {}
  promptsResponses:
    uploadBasePath: gs://BUCKET_NAME

BUCKET_NAME は、Cloud Storage バケットの名前に置き換えます。

Instrumentation カスタムリソースが更新され、ワークロードが再起動されると、プロンプトとレスポンスを構成する環境変数がワークロードのコンテナに挿入されます。

収集できるメディアの種類と、マルチモーダルプロンプトとレスポンスを調べる方法について詳しくは、マルチモーダルプロンプトとレスポンスを収集して表示するをご覧ください。

ワークロードの自動構成を無効にする

指定した構成でワークロードの自動計測を無効にするには、クラスタから Instrumentation カスタムリソースを削除します。これを行うには、次のコマンドを使用します。

kubectl delete instrumentations.telemetry.googleapis.com INSTRUMENTATION_NAME -n NAMESPACE

次のように置き換えます。

INSTRUMENTATION_NAME: Instrumentation カスタムリソースの名前。
NAMESPACE: 自動構成を無効にする Pod を含む Namespace。

自動計測構成を将来の使用のために保持しながら、環境変数の自動挿入を一時的に無効にするには、autoInstrumentationConfig.configInjection.enabled を false に設定し、更新されたカスタムリソースを適用します。

自動環境変数挿入が一時的に無効になっているカスタムリソースの例を次に示します。

apiVersion: telemetry.googleapis.com/v1alpha1
kind: Instrumentation
metadata:
  namespace: default
  name: otlp-auto-config-example
spec:
  selector:
    matchLabels: # Update the labels to match your workloads
      app: telemetrygen-app
  autoInstrumentationConfig:
    configInjection:
      enabled: false # disable environment variables config injection
  otelSDKConfig:
  ... # preserve OpenTelemetry configuration for future use

カスタムリソースを削除するか、自動構成挿入を無効にするように更新すると、GKE は Instrumentation カスタムリソースのターゲットとなる新しいワークロードを自動的に計測しません。

カスタムリソースによって以前にインストゥルメント化されたワークロードからマネージドコレクタへの OTLP シグナルのエクスポートを停止するには、変更を有効にするためにワークロードを再起動する必要があります。これを行うには、次のコマンドを使用します。

kubectl rollout restart deployment DEPLOYMENT_NAME -n NAMESPACE

次のように置き換えます。

DEPLOYMENT_NAME: デプロイメントの名前。
NAMESPACE: Namespace。

テレメトリーを表示する

Managed OpenTelemetry for GKE が有効になっている GKE で構成済みのワークロードが実行されると、OpenTelemetry シグナルが Google Cloud Observability に送信されます。

Google Cloud Observability でのデータの表示の詳細については、以下をご覧ください。

サンプルテレメトリーを生成する

このセクションでは、サンプルアプリケーションをデプロイし、そのアプリケーションがマネージド OpenTelemetry Collector の OTLP エンドポイントを参照するように設定する方法について説明します。その後、 Google Cloudでテレメトリーを表示できます。

サンプルアプリケーションは、トレース、ログ、指標をクラスタ内マネージド OpenTelemetry Collector HTTP エンドポイントにエクスポートする小さな生成ツールです。OTLP エンドポイントはアプリケーション内にハードコードされており、http://opentelemetry-collector.gke-managed-otel.svc.cluster.local:4318 を指しています。

OpenTelemetry SDK で計測されたアプリケーションがすでにある場合は、アプリケーションがコレクタのエンドポイントを参照するように設定するか、アプリケーションの自動計測を構成することで、アプリケーションからテレメトリーを生成できます。

サンプルアプリケーションをデプロイする手順は次のとおりです。

マネージド OpenTelemetry を有効にしたクラスタに接続します。これを行うには、kubectl コマンドのデフォルトクラスタを設定するをご覧ください。
次のコマンドを実行します。
```
kubectl apply -f https://raw.githubusercontent.com/GoogleCloudPlatform/otlp-k8s-ingest/main/sample/gke-app.yaml
```
数分後、アプリケーションによって生成されたテレメトリーが、シグナルごとに Collector を介して Google Cloud バックエンドに転送され始めます。
1. テレメトリーが取り込まれていることを確認するには、 Google Cloud コンソールでデモアプリケーションのログ、指標、トレースを表示します。
2. 指標を表示するには、次のようにします。
  1. Google Cloud コンソールで、[Metrics Explorer] ページに移動します。
    
    Metrics Explorer に移動
  2. Metrics Explorer で次の PromQL クエリを実行します。
```
sum(avg_over_time({"__name__"="gen","namespace"="opentelemetry-demo","job"="telemetrygen"}[1h]))
```
3. トレースを表示するには、次の操作を行います。
  1. Google Cloud コンソールで、[Trace エクスプローラ] ページに移動します。
    
    Trace エクスプローラに移動
  2. スパン名が lets-go に等しいトレーススパンをフィルタします。
4. ログを表示する手順は次のとおりです。
  1. Google Cloud コンソールで、[ログエクスプローラ] ページに移動します。
    
    [ログエクスプローラ] に移動
  2. 次のクエリを実行します。
```
resource.type="k8s_pod"
resource.labels.namespace_name="opentelemetry-demo"
```

GKE 用マネージド OpenTelemetry を無効にする

クラスタで Managed OpenTelemetry for GKE を無効にできます。コレクタを無効にすると、マネージド OpenTelemetry コレクタがクラスタから削除され、新しいテレメトリーデータは収集されなくなります。

Managed OpenTelemetry for GKE を無効にする手順は次のとおりです。

gcloud

クラスタの Managed OpenTelemetry for GKE を無効にするには、次の gcloud コマンドを実行します。

  gcloud beta container clusters update CLUSTER_NAME \
  --project=PROJECT_ID \
  --managed-otel-scope=NONE \
  --location=LOCATION

次のように置き換えます。

CLUSTER_NAME: クラスタの名前。
PROJECT_ID: Google Cloud プロジェクト ID。
LOCATION: リージョンまたはゾーン。

コンソール

コンソールで、クラスタのリストに移動します。

Kubernetes クラスタに移動
マネージド OpenTelemetry コレクタを無効にするクラスタを選択します。
[クラスタの詳細] で、[マネージド OpenTelemetry] の横にある編集アイコンを選択します。
チェックボックスをオフにすると、この機能が無効になります。

Terraform

GKE 用マネージド OpenTelemetry を無効にするには、google_container_cluster リソースの managed_opentelemetry_config ブロックを更新して、スコープを NONE に設定します。

Terraform 構成ファイルを更新します。

resource "google_container_cluster" "default" {
  provider = google-beta
  name     = "CLUSTER_NAME"
  location = "LOCATION"
  project  = "PROJECT_ID"

  # ... other configuration ...

  managed_opentelemetry_config {
    scope = "NONE"
  }
}

Terraform 構成を適用します。
```
terraform apply
```

次のように置き換えます。

CLUSTER_NAME: クラスタの名前。
LOCATION: リージョンまたはゾーン。
PROJECT_ID: Google Cloud プロジェクト ID。

GKE 用 Managed OpenTelemetry を無効にしても、Instrumentation カスタムリソース定義と Instrumentation カスタムリソースはクラスタから削除されません。マネージド OpenTelemetry を再度有効にすると、Instrumentation カスタムリソースに保存されている構成が使用されます。

Managed OpenTelemetry for GKE によってすでに収集されたテレメトリーデータがある場合、コレクタを無効にしてもこのデータには影響しません。既存のデータは Google Cloud Observability に保存されたままになり、新しいテレメトリーデータは収集されません。

トラブルシューティング

Autopilot パートナーの特権ワークロード

Autopilot パートナーの特権ワークロードで自動構成を使用しようとすると、ワークロード Pod が拒否されることがあります。

OpenTelemetry 構成の挿入は、GKE Autopilot パートナーの特権ワークロードではサポートされていません。Instrumentation カスタムリソースを使用してこのようなワークロードをターゲットにして OpenTelemetry 環境変数インジェクションを有効にすると、ワークロードが Autopilot 特権ワークロードの許可リストと一致しなくなる可能性があります。つまり、構成が挿入された Pod が GKE Autopilot によって拒否されます。

Google Cloud コンソールにログ、指標、トレースが表示されない

データが表示されない理由はさまざまです。たとえば、データを表示する権限がない、データ収集を妨げる誤った構成になっている、などです。

一般的な問題を解決するために行う手順は次のとおりです。

プロジェクトで必要な API がすべて有効になっていることを確認します。
Instrumentation カスタムリソースが正しく構成されていることを確認します。Namespace はワークロードが実行されている Namespace と一致し、セレクタはワークロードのラベルと一致している必要があります。
ワークロードの Pod を調べて、環境変数が正しく挿入されているかどうかを確認します。
OpenTelemetry Collector のコンテナログを調べて、コレクタにエラーがないかどうかを確認します。これを行うには、次のコマンドを実行します。
```
kubectl logs -n gke-managed-otel -l app=opentelemetry-collector -c opentelemetry-collector
```

テレメトリーシグナルの無効化が機能しない

Instrumentation カスタムリソースを使用してテレメトリーシグナルを無効にする場合は、カスタムリソースを適用してワークロードを再デプロイしてください。

カスタムリソースを適用するときに、Instrumentation カスタムリソースを更新する場合は、kubectl apply コマンドでサーバーサイド適用を使用します。

テレメトリーシグナルの無効化の詳細については、収集するシグナルタイプを選択するをご覧ください。

OpenTelemetry で挿入された変数がワークロードに表示されない

変数はワークロードではなく、ワークロード Pod のコンテナに挿入されます。ReplicaSet や Deployment などのオーナーオブジェクトではなく、Pod を確認します。

たとえば、前のセクションのテレメトリーを生成するで使用したデフォルトの Namespace のサンプルワークロードで変数が正しく挿入されていることを確認するには、次の操作を行います。

次のコマンドを実行します。

kubectl get pods -n default -l app=telemetrygen-app -o yaml

Pod の spec.containers[*].env を調べます。
同じ Namespace に Instrumentation オブジェクトが存在することを確認し、Pod をターゲットにして構成インジェクション機能が有効になっていることを確認します。これを行うには、次のコマンドを実行します。
```
kubectl get instrumentations.telemetry.googleapis.com -n default -o yaml
```

Kubernetes API では、環境変数など、既存の Pod の仕様のほとんどのフィールドを変更できないため、変数は Pod の作成時にのみコンテナに挿入されます。Instrumentation オブジェクトを作成する前に作成されたワークロードに構成を適用するには、ワークロードを再起動します。たとえば、telemetry-gen-app という名前の Deployment の場合は、次のコマンドを実行します。

kubectl rollout restart deployment -n default telemetry-gen-app

Cloud Trace のトレースデータが多すぎる

Cloud Trace で収集されるデータを減らすには、トレース ID 比率で親ベースのサンプラーを構成して、トレースの割合のみをサンプリングします。

たとえば、Instrumentation オブジェクトに次のように追加します。

spec:
  otelSDKConfig:
    tracer_provider:
      sampler:
        parent_based:
          root:
            trace_id_ratio_based:
              ratio: "0.01"

デフォルトの OpenTelemetry SDK の動作は「always_on」トレースで、比率 1 と同等です。

環境変数が構成と一致しない

Instrumentation オブジェクトを更新した場合は、構成を変更するセクションの説明に沿って Pod を再起動したことを確認してください。

Pod の構成が間違っている場合は、Pod が Instrumentation オブジェクトによって正しくターゲット設定されていること、同じ Pod をターゲットとする複数の Instrumentation オブジェクトがないことを確認します。

kubectl get instrumentations --all-namespaces \
-o custom-columns=NAMESPACE:.metadata.namespace,NAME:.metadata.name,SELECTOR:.spec.selector

kubectl get pod -n ${NAMESPACE:?} ${POD_NAME:?} --show-labels

空のセレクタは、その Namespace 内のすべての Pod をターゲットにします。

作成時に複数の計測が同じ Pod をターゲットにしている場合、最後に更新された計測が有効になります。

`kubectl logs` コマンドは出力を返しません

ログがアプリケーションから OpenTelemetry コレクタに直接ストリーミングされる場合、ログはコンテナランタイムの標準ロギングパスをバイパスします。これは、ログに OpenTelemetry を使用する場合の一般的なシナリオです。デフォルトでは、エクスポーターは stdout ストリームと stderr ストリームではなく、otlp エンドポイントにログを送信します。

この場合、ログはコンテナランタイムがキャプチャする stdout ストリームまたは stderr ストリームに書き込まれないため、kubectl logs コマンドはそのアプリケーションの出力を表示しません。代わりに、ロギング出力は Cloud Logging で確認できます。

OpenTelemetry SDK を使用して stdout ストリームにログを送信する場合は、ログエクスポータを使用して構成できます。詳細については、ログエクスポータ - 標準出力をご覧ください。

次のステップ

GKE 用マネージド OpenTelemetry の仕組みの詳細については、GKE 用マネージド OpenTelemetry をご覧ください。
GKE 用マネージド OpenTelemetry のセルフデプロイの代替については、Google が構築した OpenTelemetry Collector をご覧ください。

GKE 用マネージド OpenTelemetry をデプロイする コレクションでコンテンツを整理 必要に応じて、コンテンツの保存と分類を行います。

始める前に

要件

必要なロール

費用

クラスタで GKE 用マネージド OpenTelemetry を有効にする

新しいクラスタで有効にする

gcloud

コンソール

Terraform

既存のクラスタで有効にする

gcloud

コンソール

Terraform

マネージド OpenTelemetry コレクタを使用するようにアプリケーションを構成する

自動構成を設定する

構成を変更する

データの収集の量や頻度を変更する

トレースのサンプリング レートを変更する

指標のエクスポート間隔を変更する

収集するシグナルタイプを選択する

マルチモーダル プロンプトとレスポンスのデータを収集する

ワークロードの自動構成を無効にする

テレメトリーを表示する

サンプル テレメトリーを生成する

GKE 用マネージド OpenTelemetry を無効にする

gcloud

コンソール

Terraform

トラブルシューティング

Autopilot パートナーの特権ワークロード

Google Cloud コンソールにログ、指標、トレースが表示されない

テレメトリー シグナルの無効化が機能しない

OpenTelemetry で挿入された変数がワークロードに表示されない

Cloud Trace のトレースデータが多すぎる

環境変数が構成と一致しない

kubectl logs コマンドは出力を返しません

次のステップ

GKE 用マネージド OpenTelemetry をデプロイする

トレースのサンプリングレートを変更する

マルチモーダルプロンプトとレスポンスのデータを収集する

サンプルテレメトリーを生成する

テレメトリーシグナルの無効化が機能しない

`kubectl logs` コマンドは出力を返しません