GKE 用マネージド OpenTelemetry

このドキュメントでは、Google Kubernetes Engine（GKE）用マネージド OpenTelemetry について説明します。 これにより、GKE で実行されているアプリケーションから OpenTelemetry Protocol（OTLP） のトレース、指標、ログを Google Cloud Observability に送信できます。マネージド OpenTelemetry は、GKE でトレースデータを収集するための Google Cloud の唯一のマネージド ソリューションです。

Google Kubernetes Engine（GKE）用マネージド OpenTelemetry を使用するには、OpenTelemetry プロトコルを使用してシグナルを生成するようにアプリケーションを事前に計測する必要があります。 詳細については、 対応しているワークロードをご覧ください。

GKE 用マネージド OpenTelemetry には次の 2 つのコンポーネントがあります。

  • マネージド モードでの収集: マネージド コレクタは、コレクタを管理することなく、ワークロードが OTLP 形式でトレース、指標、ログを送信する宛先として、クラスタ内 OpenTelemetry Protocol エンドポイントを提供します。

  • 自動構成: カスタム リソース と呼ばれる Instrumentation を使用すると、GKE ワークロードの自動構成が可能になり、 関連する OpenTelemetry トレース、指標、ログを生成して取り込むことができます。 このアプローチでは、 Agent Development Kit（ADK） とマルチモーダル プロンプトとレスポンスのデータをサポートしています。

    Instrumentation カスタム リソースは、OpenTelemetry SDK を使用し、標準の OpenTelemetry 環境変数で構成されたワークロードに使用できます。この Instrumentation カスタム リソース instrumentations.telemetry.googleapis.com は、OpenTelemetry Operator の Instrumentation リソースとは異なるリソースです。

GKE 用マネージド OpenTelemetry を使用する手順については、 GKE 用マネージド OpenTelemetry をデプロイするをご覧ください。

GKE 用マネージド OpenTelemetry を使用すると、OpenTelemetry Collector を管理、運用することなく、OTLP テレメトリーを収集できます。独自のコレクタを実行すると、認証、構成、アップグレード、モニタリングなどのオーバーヘッドが発生する可能性があります。 ただし、コレクタレベルのフィルタリングと制御が必要な場合は、このマネージドサービスではなく、 Google が構築した OpenTelemetry Collector を使用できます。

OpenTelemetry は、アプリケーション モニタリング用に分散トレース、指標、ログを生成するための API、ライブラリ、SDK を提供します。OpenTelemetry の詳細については、 OpenTelemetry と OpenTelemetry Protocol（OTLP）に関するドキュメントをご覧ください。 アプリケーションのランタイム動作データの生成と収集の詳細については、計測とオブザーバビリティをご覧ください。

GKE 用マネージド OpenTelemetry の仕組み

GKE 用マネージド OpenTelemetry には、マネージド モードでの収集と自動構成の 2 つのコンポーネントがあります。

マネージド モードでの収集

マネージド モードでの収集では、マネージド OpenTelemetry Collector をクラスタにデプロイすることで、クラスタ内 OTLP エンドポイントが提供されます。このクラスタ内 OTLP エンドポイントは、OTLP 形式のトレース、指標、ログを受信します。ワークロードからデータを受信するには、コレクタにデータを送信するようにワークロードを構成する必要があります。

マネージド コレクタのエンドポイントは http://opentelemetry-collector.gke-managed-otel.svc.cluster.local:4318 です。

マネージド モードでの収集では、収集したデータが Google Cloud Observability に送信されます。データは次のサービスで利用できます。

マネージド コレクタは、コンソールまたは gcloud CLI を使用して GKE クラスタで有効にできます。手順については、 クラスタで GKE 用マネージド OpenTelemetry を有効にするをご覧ください。

自動構成

自動構成を使用すると、GKE で実行されているワークロードがマネージド コレクタのエンドポイントにシグナルを送信するように GKE を構成できます。

ワークロードを構成するには、さまざまな方法があります。 自動構成では、ワークロードのコンテナに挿入された環境変数を使用して、ワークロードがマネージド コレクタにシグナルを送信するようにします。 ワークロードを手動で構成する場合は、他の方法を使用できます。詳細については、 手動設定をご覧ください。

自動構成を使用する場合は、Instrumentation カスタム リソースを使用して構成を定義します。次に、GKE は OTLP エクスポータ エンドポイントなどの環境変数をワークロードのコンテナに挿入します。ワークロードのコンテナにこれらの環境変数がある場合、ワークロードの実行時に OpenTelemetry データがマネージド コレクタに送信されます。

自動構成は、OpenTelemetry をネイティブにサポートするワークロードで使用できます。つまり、OpenTelemetry SDK を使用し、標準の OpenTelemetry 環境変数を使用して構成されます。 詳細については、 対応しているワークロードをご覧ください。

自動構成を使用してアプリケーションを構成する手順については、 マネージド OpenTelemetry Collector を使用するようにアプリケーションを構成するをご覧ください。

Instrumentation カスタム リソース

Instrumentation カスタム リソースを使用して、次の操作を行います。

  • 選択した Pod のコンテナまたは Namespace 内のすべての Pod のコンテナに環境変数を挿入するかどうかを指定します。
  • 収集するデータの種類（ログ、指標、トレース）を制御します。
  • 指標データがマネージド コレクタに送信される頻度を制御します。
  • トレースデータのサンプリング レートを制御します。

Instrumentation カスタム リソースの使用方法の詳細については、 構成を変更するをご覧ください。

環境変数を自動的に挿入する

OpenTelemetry 環境変数を GKE ワークロードに自動的に挿入するには、クラスタに Instrumentation オブジェクトを構成する必要があります。 次に、Instrumentation オブジェクトを使用してクラスタにアプリケーションをデプロイすると、変数が GKE によって挿入されます。

アプリケーションがデプロイされ、Pod が作成されるときに、Instrumentation オブジェクトがクラスタに存在する必要があります。Instrumentation オブジェクトを作成する前にアプリケーションをデプロイした場合は、アプリケーションの Pod を再起動して、環境変数の自動挿入をトリガーする必要があります。

環境変数

自動構成が有効になっている Namespace にワークロードがデプロイされると、GKE は環境変数をワークロードのコンテナに挿入します。これらの環境 変数は、 OpenTelemetry SDK 構成の OpenTelemetry 変数です。

次のリストには、GKE 用マネージド OpenTelemetry によって挿入できるすべての環境変数が含まれています。コンテナに挿入される特定の環境変数は、Instrumentation カスタム リソースの構成によって異なります。

コンテナに自動的に挿入できる環境変数は次のとおりです。

  • OpenTelemetry エクスポータ エンドポイント。
    • OTEL_EXPORTER_OTLP_ENDPOINT: 任意のシグナル タイプのベース エンドポイント URL。このエンドポイントは常に、ログ、指標、トレースのクラスタ内マネージド OpenTelemetry Collector HTTP エンドポイントを指します。 エンドポイントは http://opentelemetry-collector.gke-managed-otel.svc.cluster.local:4318 です。
  • トレース サンプリング比率の構成。
      • OTEL_TRACES_SAMPLER：SDK がトレースをサンプリングするために使用するサンプラーを次のいずれかに設定します。
      • カスタム リソースでトレース サンプリングが構成されている場合は parentbased_traceidratio。
      • parentbased_always_on は、この環境変数のデフォルト値です。 この環境変数が構成されていない場合、またはカスタム リソースで null の場合は、この環境変数が使用されます。
    • OTEL_TRACES_SAMPLER_ARG: トレース サンプリング比率（0.0 ～ 1.0）を指定します。カスタム リソースで構成されていない場合は、1.0 が使用されます。
  • 連続する 2 つの指標エクスポートの開始間の遅延間隔。
    • OTEL_METRIC_EXPORT_INTERVAL: 2 回のエクスポート試行の開始間の時間間隔（ミリ秒単位）（最小: 5000、最大: 300000、デフォルト: 30000）。
  • シグナル タイプ別の OTLP テレメトリー エクスポートの無効化。Instrumentation ファイルで tracer_provider、meter_provider、logger_provider が null に設定されている場合、シグナル エクスポータは無効になります。
    • OTEL_TRACES_EXPORTER: none に設定すると、トレースのエクスポートが無効になります。デフォルト値: otlp。
    • OTEL_METRICS_EXPORTER: none に設定すると、指標のエクスポートが無効になります。デフォルト値: otlp。
    • OTEL_LOGS_EXPORTER: none に設定すると、ログのエクスポートが無効になります。デフォルト値: otlp。
  • OpenTelemetry Collector の Kubernetes Attributes Processor でメタデータを関連付けるための hostNetwork Pod の識別。
    • K8S_POD_UID: OTEL_RESOURCE_ATTRIBUTES 環境変数の k8s.pod.uid 設定を設定するための hostNetwork Pod の Pod UID。
    • OTEL_RESOURCE_ATTRIBUTES: 値には k8s.pod.uid=$(K8S_POD_UID) が含まれており、Kubernetes Attributes Processor が k8s.namespace.name、k8s.deployment.name、k8s.node.name などのメタデータを hostNetwork Pod に関連付けることができます。 メタデータと hostNetwork Pod を関連付けることで、抽出されたメタデータをリソース属性としてスパン、指標、ログに追加できます。
  • プロンプトとレスポンス。
    • OTEL_INSTRUMENTATION_GENAI_UPLOAD_FORMAT='jsonl': Cloud Storage オブジェクトを JSON Lines としてフォーマットするように OpenTelemetry に指示します。この環境変数の値は jsonl に固定されています。
    • OTEL_INSTRUMENTATION_GENAI_COMPLETION_HOOK='upload': このコンテンツをトレーススパンに埋め込むのではなく、プロンプトとレスポンスのデータをアップロードするように OpenTelemetry に指示します。アップロードされたオブジェクトへの参照がログエントリに含まれます。この環境変数の値は upload に固定されています。
    • OTEL_SEMCONV_STABILITY_OPT_IN='gen_ai_latest_experimental': 生成 AI の最新のセマンティック規約を使用するように OpenTelemetry に指示します。この環境変数の値は gen_ai_latest_experimental に固定されています。
    • OTEL_INSTRUMENTATION_GENAI_UPLOAD_BASE_PATH: オブジェクトのパスを指定します。例: gs://STORAGE_BUCKET_NAME/PATH

手動設定

ワークロードを構成してマネージド コレクタのエンドポイントにシグナルを送信するには、さまざまな方法があります。ワークロードを手動で構成する場合は、環境変数を手動で追加して変更するか、コマンドライン フラグなどの別の方法を使用できます。

同じワークロードに手動構成と自動構成の両方を使用することはおすすめしません。自動構成によって手動での変更がオーバーライドされる可能性があるためです。この組み合わせにより、構成の変更を追跡することが難しくなる可能性があります。

自動構成の詳細については、 自動構成をご覧ください。

対応しているワークロード

対応しているワークロードは、OpenTelemetry を使用してアプリケーションのランタイム動作に関するデータを収集するワークロードです。OpenTelemetry SDK を使用し、標準の OpenTelemetry 環境変数を使用して構成されている場合、ワークロードは OpenTelemetry をネイティブにサポートします。たとえば、 Agent Development Kit（ADK） は OpenTelemetry をネイティブにサポートしています。

アプリケーションのランタイム動作データの生成と収集の詳細については、 計測とオブザーバビリティをご覧ください。

ワークロードが一部の OTLP データをサポートし、他の OTLP データをサポートしていない場合、GKE 用マネージド OpenTelemetry は OTLP データを収集します。たとえば、ワークロードが OpenTelemetry SDK を使用してトレースを実装しているが、ログや指標には使用していない場合、ログと指標のデータは GKE 用マネージド OpenTelemetry によって収集されません。収集するデータの種類を 制御する方法については、 収集するシグナル タイプを選択するをご覧ください。

GKE Autopilot パートナーの 特権ワークロードでは、OpenTelemetry 構成の挿入はサポートされていません。

課金

テレメトリー データを Google Cloudに送信する場合は、取り込み 量に基づいて課金されます。指標は Google Cloud Managed Service for Prometheus の料金で課金され、ログは Cloud Logging の料金で課金され、トレースは Cloud Trace の料金で課金されます。

トレース、ログ、 Google Cloud Managed Service for Prometheus 指標の取り込みに関連する費用については、 Google Cloud Observability の料金をご覧ください。

割り当て

GKE 用マネージド OpenTelemetry を使用する場合、Google Cloud Observability サービスの割り当てが適用されます。詳細については、以下をご覧ください。

次のステップ