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

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

Autopilot Standard

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

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

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

GKE で実行されているワークロードを構成して、OpenTelemetry Protocol（OTLP）のトレース、指標、ログをマネージドコレクタに送信します。
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 権限が必要です。プロジェクトを作成した場合は、オーナーロール（roles/owner）を介してこの権限がすでに付与されている可能性があります。それ以外の場合は、Service Usage 管理者ロール（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

要件

GKE 用マネージド OpenTelemetry を使用するには、次の要件を満たす必要があります。

クラスタに GKE バージョン 1.34.1-gke.2178000 以降がインストールされている必要があります。Instrumentation カスタムリソースで OTLP エクスポートプロトコルを構成して gRPC として使用するには、GKE バージョン 1.37.1-gke.1697000 以降を使用する必要があります。
gcloud CLI バージョン 576.0.0 以降が有効になっている。
Terraform を使用して GKE インフラストラクチャをプロビジョニングする場合は、バージョン v8.8.0 以降の terraform-provider-google を使用する必要があります。

必要なロール

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

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

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

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

費用

GKE 用マネージド OpenTelemetry の使用に関連する費用の詳細については、課金をご覧ください。

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

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

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

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

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

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

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

新しいクラスタで GKE 用マネージド OpenTelemetry を有効にするには、次の操作を行います。

gcloud

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

gcloud 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: GKE のバージョン。使用可能な最小バージョンについては、要件をご覧ください。

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

gcloud 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: GKE のバージョン。使用できる最小バージョンについては、要件をご覧ください。

コンソール

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

Terraform

Terraform を使用して新しいクラスタで GKE 用マネージド OpenTelemetry を有効にするには、次の例をご覧ください。

terraform {
  required_providers {
    google = {
      source  = "hashicorp/google"
      version = ">= 8.8.0"
    }
  }
}

resource "google_container_cluster" "default" {
  name     = "gke-standard-regional-with-managed-otel"
  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 のサポートをご覧ください。

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

既存のクラスタで GKE 用マネージド OpenTelemetry を有効にする手順は次のとおりです。

gcloud

クラスタバージョンが要件を満たしていることを確認します。既存のクラスタをアップグレードする方法については、Standard クラスタのアップグレードと Autopilot クラスタのアップグレードをご覧ください。
次のコマンドを使用して、GKE 用のマネージド OpenTelemetry を有効にします。
```
gcloud 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: リージョンまたはゾーン。

コンソール

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

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

Terraform

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

terraform {
  required_providers {
    google = {
      source  = "hashicorp/google"
      version = ">= 8.8.0"
    }
  }
}

resource "google_container_cluster" "default" {
  name     = "gke-standard-regional-with-managed-otel"
  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 Collector を使用するようにアプリケーションを構成する

マネージドコレクタのエンドポイントにシグナルを送信できるように、アプリケーションを構成する必要があります。アプリケーションが構成されると、マネージド 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: マニフェストファイル内の Instrumentation オブジェクトの名前。
  - （省略可）ターゲットとする 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
```
環境変数を自動的に挿入するには、構成が適用されているクラスタ内の名前空間にアプリケーションをデプロイする必要があります。
- 名前空間でまだ実行されていないワークロードに構成を適用するには、次のコマンドを使用してワークロードをデプロイします。
```
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 でアプリケーションを再デプロイまたは再起動します。

これらの手順の詳細については、自動構成を設定するの手順をご覧ください。

OTLP エクスポートプロトコル（HTTP または gRPC）を構成する

デフォルトでは、自動構成により、HTTP 経由でテレメトリーをエクスポートするようにワークロードが設定されます。GKE バージョン 1.37.1-gke.1697000 以降では、HTTP または gRPC 経由でテレメトリーをエクスポートするように Instrumentation カスタムリソースを構成できます。

Instrumentation カスタムリソースは、すべてのプロバイダに対して 1 つのプロトコルのみをサポートします。gRPC を使用するには、使用するプロバイダごとにエクスポータを otlp_grpc: {} に設定し、未使用のプロバイダを null に設定します。たとえば、指標を無効にするには、meter_provider: null を使用します。

次の例は、トレース、指標、ロギングプロバイダの gRPC 経由でテレメトリーをエクスポートするように構成された Instrumentation マニフェストファイルです。

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"
      processors:
      - batch:
          exporter:
            otlp_grpc: {}
    meter_provider:
      readers:
      - periodic:
          interval: METRICS_INTERVAL
          exporter:
            otlp_grpc: {}
    logger_provider:
      processors:
      - batch:
          exporter:
            otlp_grpc: {}

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

NAMESPACE: 自動計測の対象とする Pod を含む Namespace。default を使用して、デフォルトの Namespace をターゲットにします。
NAME: マニフェストファイル内の Instrumentation オブジェクトの名前。
（省略可）ターゲットとする Pod に適用されるラベル。空のセレクタが指定されている場合（{}）、Namespace 内のすべての Pod が対象になります。
- KEY: ラベルのキー。
- VALUE: ラベルの値。
TRACE_RATIO: 収集するトレースデータの比率。指定しない場合は、デフォルトの 1.0 が使用されます。詳細については、トレースサンプリングレートを変更するをご覧ください。
METRICS_INTERVAL: 収集するモニタリングデータの間隔（ミリ秒単位）。デフォルトは 30000 です。値は負でない値で、最小値は 5,000 ミリ秒、最大値は 300,000 ミリ秒、5,000 ミリ秒の倍数にする必要があります。詳細については、指標のエクスポート間隔を変更するをご覧ください。

データの収集の量または頻度を変更する

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

モニタリングデータが 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 つの連続したエクスポートの開始間の遅延間隔を指定するために使用されます。

この間隔の値は、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 クラスタバージョン 1.35.2-gke.1210000 以降では、マルチモーダルプロンプトとレスポンスデータを収集するように GKE 用マネージド OpenTelemetry を構成できます。

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

Managed OpenTelemetry for GKE を使用してマルチモーダルプロンプトとレスポンスのデータを収集すると、エンドユーザーのプロンプトとレスポンスの完全な内容が収集されます。このプロンプトとレスポンスのデータは、Cloud Storage バケットに保存されます。アクセス制御やデータの削除など、ストレージバケットの管理方法については、Cloud Storage のドキュメントをご覧ください。

Model Armor や Sensitive Data Protection などのプロダクトを使用して、プロンプトやレスポンスに含まれる可能性のある機密データを管理できます。

マルチモーダルプロンプトとレスポンスデータを収集するように 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 にエクスポートする小さな生成ツールです。アプリケーションは、コレクタの gRPC エンドポイント（http://opentelemetry-collector.gke-managed-otel.svc.cluster.local:4317）を使用するようにハードコードされています。

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

サンプルアプリケーションをデプロイするには、次の操作を行います。

マネージド OpenTelemetry を有効にしたクラスタに接続します。これを行うには、kubectl コマンドのデフォルトクラスタを設定するをご覧ください。
次のコマンドを実行します。
```
kubectl apply -f https://raw.githubusercontent.com/GoogleCloudPlatform/otlp-k8s-ingest/main/sample/gke-app.yaml
```
数分後、アプリケーションによって生成されたテレメトリーが、シグナルごとにコレクタを介して 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 を無効にする

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

GKE 用マネージド OpenTelemetry を無効にするには、次の操作を行います。

gcloud

クラスタで GKE 用マネージド OpenTelemetry を無効にするには、次の gcloud コマンドを実行します。

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

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

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

コンソール

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

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

Terraform

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

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

resource "google_container_cluster" "default" {
  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 CustomResourceDefinition と作成した 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 を確認します。

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

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

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

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

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

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

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

次のステップ

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

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

始める前に

要件

必要なロール

費用

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

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

gcloud

コンソール

Terraform

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

gcloud

コンソール

Terraform

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

自動構成を設定する

構成を変更する

OTLP エクスポート プロトコル（HTTP または gRPC）を構成する

データの収集の量または頻度を変更する

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

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

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

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

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

テレメトリーを表示する

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

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

gcloud

コンソール

Terraform

トラブルシューティング

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

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

テレメトリー信号を無効にできない

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

Cloud Trace のトレースデータが過剰

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

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

次のステップ

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

OTLP エクスポートプロトコル（HTTP または gRPC）を構成する

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

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

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

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