GKE 的代管 OpenTelemetry

本文說明 Google Kubernetes Engine (GKE) 適用的代管 OpenTelemetry，可讓您將 OpenTelemetry Protocol (OTLP) 追蹤記錄、指標和記錄，從 GKE 上執行的應用程式傳送至 Google Cloud Observability。Managed OpenTelemetry 是 Google Cloud 唯一的代管解決方案，可在 GKE 上收集追蹤記錄資料。

如要使用 Google Kubernetes Engine (GKE) 適用的 Managed OpenTelemetry，應用程式必須已檢測，可使用 OpenTelemetry 通訊協定產生信號。詳情請參閱「支援的工作負載」。

GKE 專用代管 OpenTelemetry 包含兩個元件：

  • 代管收集器：代管收集器提供叢集內 OpenTelemetry Protocol 端點，做為工作負載的目的地，以 OTLP 格式傳送追蹤記錄、指標和記錄，不必管理收集器。

  • 自動設定：名為「檢測」的自訂資源可自動設定 GKE 工作負載，產生及擷取相關聯的 OpenTelemetry 追蹤記錄、指標和記錄。這個方法支援 Agent Development Kit (ADK) 和多模態提示和回覆資料。

    如果工作負載使用 OpenTelemetry SDK，並設定標準 OpenTelemetry 環境變數，您可以使用 Instrumentation 自訂資源。這個檢測自訂資源 instrumentations.telemetry.googleapis.com 與 OpenTelemetry 運算子的檢測資源不同。

如要瞭解如何使用 Managed OpenTelemetry for GKE，請參閱「部署 Managed OpenTelemetry for GKE」。

有了 GKE 適用的代管 OpenTelemetry，您不必管理及操作 OpenTelemetry 收集器，即可收集 OTLP 遙測資料。自行執行收集器可能會產生額外負擔，包括驗證、設定、升級和監控。不過，如果您需要收集器層級的篩選和控制功能，可以使用 Google 建構的 OpenTelemetry 收集器，而非這項代管服務。

OpenTelemetry 提供 API、程式庫和 SDK，可產生分散式追蹤記錄、指標和記錄，用於監控應用程式。如要進一步瞭解 OpenTelemetry，請參閱 OpenTelemetry 和 OpenTelemetry 通訊協定 (OTLP) 的說明文件。如要進一步瞭解如何產生及收集應用程式的執行階段行為數據，請參閱「應用程式開發人員的觀測能力」。

GKE 專用代管 OpenTelemetry 的運作方式

GKE 適用的代管 OpenTelemetry 包含兩個元件：代管收集和自動設定。

代管集合

代管收集功能會將代管 OpenTelemetry 收集器部署至叢集，提供叢集內 OTLP 端點。這個叢集內 OTLP 端點會接收 OTLP 格式的追蹤記錄、指標和記錄。如要從工作負載接收資料，必須將工作負載設為將資料傳送至收集器。

工作負載傳送資料的端點取決於您使用的通訊協定，如下所示：

  • HTTP 端點的 http://opentelemetry-collector.gke-managed-otel.svc.cluster.local:4318 網址。
  • gRPC 端點的 http://opentelemetry-collector.gke-managed-otel.svc.cluster.local:4317 網址。

代管收集功能會將收集到的資料傳送至 Google Cloud Observability。接著，您可以在下列服務中使用這些資料：

您可以使用控制台或 gcloud CLI，為 GKE 叢集啟用代管收集器。如需操作說明，請參閱「在叢集中啟用 GKE 適用的代管 OpenTelemetry」。

自動設定

自動設定可讓 GKE 設定在 GKE 上執行的工作負載，將信號傳送至代管收集器的端點。

設定工作負載的方法有很多種。自動設定會使用插入工作負載容器的環境變數，讓工作負載將信號傳送至代管收集器。如果您是手動設定工作負載，則可使用其他方法。詳情請參閱「手動設定」。

使用自動設定時，您可以使用 Instrumentation 自訂資源定義設定。接著，GKE 會將環境變數 (例如 OTLP 匯出工具端點) 插入工作負載的容器。如果工作負載的容器有這些環境變數，則工作負載執行時，OpenTelemetry 資料會傳送至代管收集器。

原生支援 OpenTelemetry 的工作負載可自動設定，也就是說，這些工作負載會使用 OpenTelemetry SDK，並透過標準 OpenTelemetry 環境變數設定。詳情請參閱「支援的工作負載」。

如需使用自動設定來設定應用程式的操作說明，請參閱「將應用程式設為使用代管 OpenTelemetry 收集器」。

檢測自訂資源

您可以透過檢測自訂資源執行下列操作：

  • 指定是否要將環境變數插入所選 Pod 的容器，或命名空間中所有 Pod 的容器。
  • 控管收集的資料類型 (記錄、指標和追蹤記錄)。
  • 控制將指標資料傳送至代管收集器的頻率。
  • 控管追蹤資料的取樣率。
  • 控管用於將遙測資料匯出至代管收集器的 OTLP 傳輸通訊協定 (HTTP 或 gRPC)。

如要進一步瞭解如何使用檢測自訂資源，請參閱「修改設定」。

自動插入環境變數

如要自動將 OpenTelemetry 環境變數插入 GKE 工作負載，您必須在叢集中設定 Instrumentation 物件。接著，當您使用檢測物件在叢集中部署應用程式時，GKE 就會插入變數。

部署應用程式並建立 Pod 時，Instrumentation 物件必須位於叢集中。如果您在建立檢測物件之前就部署了應用程式，則需要重新啟動應用程式的 Pod，才能觸發環境變數的自動插入功能。

環境變數

將工作負載部署至已啟用自動設定的命名空間時，GKE 會將環境變數插入工作負載的容器。這些環境變數是 OpenTelemetry SDK 設定中的 OpenTelemetry 變數。

下列清單包含可由 Managed OpenTelemetry for GKE 插入的所有環境變數。插入容器的特定環境變數，取決於檢測自訂資源中的設定。

可自動插入容器的環境變數如下：

  • OpenTelemetry 匯出工具端點和通訊協定。
    • OTEL_EXPORTER_OTLP_ENDPOINT：任何信號類型的基本端點網址。視檢測自訂資源中設定的匯出工具而定，這個環境變數的值是叢集內代管的 OpenTelemetry 收集器 HTTP 端點 (http://opentelemetry-collector.gke-managed-otel.svc.cluster.local:4318，預設) 或 gRPC 端點 (http://opentelemetry-collector.gke-managed-otel.svc.cluster.local:4317)。
    • OTEL_EXPORTER_OTLP_PROTOCOL：指定 SDK 匯出工具使用的 OTLP 傳輸通訊協定。這個環境變數的值取決於您使用的 OTLP 傳輸通訊協定，可能是下列其中一項：
      • 如果使用 otlp_grpc 傳輸通訊協定，則為 grpc。
      • 如果您未指定傳輸通訊協定，或使用 otlp_http 傳輸通訊協定，則為 http/protobuf。
  • 追蹤記錄取樣率設定。
    • OTEL_TRACES_SAMPLER：將 SDK 用於取樣追蹤記錄的取樣器設為下列其中一項：
      • 在自訂資源中設定追蹤記錄取樣時，parentbased_traceidratio。
      • parentbased_always_on 是這個環境變數的預設值。如果未設定這個環境變數，或自訂資源中的環境變數為空值，系統就會使用這個變數。
    • OTEL_TRACES_SAMPLER_ARG：指定追蹤記錄取樣率 (介於 0.0 和 1.0 之間)。如未在自訂資源中設定，則會使用 1.0。
  • 連續兩項指標匯出作業開始時間之間的延遲間隔。
    • OTEL_METRIC_EXPORT_INTERVAL：兩次匯出嘗試開始之間的時間間隔 (以毫秒為單位，最小值：5000，最大值：300000，預設值：30000)。
  • 依信號類型停用 OTLP 遙測匯出功能。如果檢測自訂資源中的 tracer_provider、meter_provider 或 logger_provider 設為 null，信號匯出工具就會停用。
    • OTEL_TRACES_EXPORTER：設為 none 時，會停用追蹤記錄匯出功能。預設值：otlp。
    • OTEL_METRICS_EXPORTER：設為 none 時，會停用指標匯出功能。預設值：otlp。
    • OTEL_LOGS_EXPORTER：設為 none 時，會停用記錄匯出功能。預設值：otlp。
  • 識別 hostNetwork Pod，以便透過 OpenTelemetry Collector 的 Kubernetes 屬性處理器建立中繼資料關聯。
    • K8S_POD_UID：hostNetwork Pod 的 Pod UID，用於填入 OTEL_RESOURCE_ATTRIBUTES 環境變數中的 k8s.pod.uid 設定。
    • OTEL_RESOURCE_ATTRIBUTES：值包含 k8s.pod.uid=$(K8S_POD_UID)，允許 Kubernetes 屬性處理器將中繼資料 (例如 k8s.namespace.name、k8s.deployment.name 和 k8s.node.name) 與 hostNetwork Pod 建立關聯。中繼資料和 hostNetwork Pod 的關聯，可讓您將擷取的中繼資料新增至 span、指標和記錄，做為資源屬性。
  • 提示詞和回覆。
    • OTEL_INSTRUMENTATION_GENAI_UPLOAD_FORMAT='jsonl'：指示 OpenTelemetry 將 Cloud Storage 物件格式化為 JSON Lines。這個環境變數的值固定為 jsonl。
    • OTEL_INSTRUMENTATION_GENAI_COMPLETION_HOOK='upload'：指示 OpenTelemetry 上傳提示和回應資料，而非將這類內容嵌入追蹤記錄 span。記錄項目會包含上傳物件的參照。這個環境變數的值固定為 upload。
    • OTEL_SEMCONV_STABILITY_OPT_IN='gen_ai_latest_experimental'：指示 OpenTelemetry 使用最新的生成式 AI 語意慣例。這個環境變數有固定值：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 資料，但不支援其他類型，則 GKE 適用的 Managed OpenTelemetry 會收集 OTLP 資料。舉例來說，如果工作負載使用 OpenTelemetry SDK 實作追蹤記錄，但未使用該 SDK 處理記錄或指標，則 GKE 適用的 Managed 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 定價」。

配額

使用 Managed OpenTelemetry for GKE 時，適用 Google Cloud Observability 服務的配額。詳情請參閱下列文章：

後續步驟