GKE 的代管 OpenTelemetry

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

如要使用 Google Kubernetes Engine (GKE) 的代管 OpenTelemetry，應用程式必須已完成檢測，才能使用 OpenTelemetry 協定產生信號。詳情請參閱「支援的工作負載」。

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

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

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

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

如要瞭解如何使用 GKE 適用的代管 OpenTelemetry，請參閱「部署 GKE 適用的代管 OpenTelemetry」。

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

OpenTelemetry 提供 API、程式庫和 SDK，可產生分散式追蹤記錄、指標和記錄，用於監控應用程式。如要進一步瞭解 OpenTelemetry，請參閱 OpenTelemetry 和 OpenTelemetry Protocol (OTLP) 的說明文件。如要進一步瞭解如何產生及收集應用程式的執行階段行為資料，請參閱「檢測和可觀測性」。

GKE 代管 OpenTelemetry 的運作方式

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

代管型集合

代管收集功能會在叢集中部署代管 OpenTelemetry 收集器，提供叢內 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 環境變數設定，即可自動設定。詳情請參閱「支援的工作負載」。

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

Instrumentation 自訂資源

您可以使用 Instrumentation 自訂資源執行下列操作：

  • 指定要將環境變數注入所選 Pod 的容器，還是命名空間中的所有 Pod 容器。
  • 控管收集的資料類型 (記錄、指標和追蹤記錄)。
  • 控制指標資料傳送至代管收集器的頻率。
  • 控制追蹤記錄資料的取樣率。

如要瞭解如何使用 Instrumentation 自訂資源，請參閱「修改設定」。

自動插入環境變數

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

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

環境變數

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

下表列出 Managed OpenTelemetry for GKE 可注入的所有環境變數。注入容器的特定環境變數取決於 Instrumentation 自訂資源中的設定。

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

  • OpenTelemetry 匯出工具端點。
    • OTEL_EXPORTER_OTLP_ENDPOINT：任何信號類型的基準端點網址。這個端點一律指向叢集內受管理的 OpenTelemetry 收集器 HTTP 端點，用於記錄、指標和追蹤記錄。端點為： http://opentelemetry-collector.gke-managed-otel.svc.cluster.local:4318。
  • 追蹤記錄取樣率設定。
    • 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 在 Instrumentation 檔案中設為 null，信號匯出工具就會停用。
    • OTEL_TRACES_EXPORTER：設為 none 時，會停用追蹤記錄匯出功能。預設值為 otlp。
    • OTEL_METRICS_EXPORTER：設為 none 時，會停用指標匯出功能。預設值為 otlp。
    • OTEL_LOGS_EXPORTER：設為 none 時，會停用記錄匯出功能。預設值為 otlp。
  • 識別 hostNetwork Pod，以透過 OpenTelemetry Collector 的 Kubernetes 屬性處理器關聯中繼資料。
    • K8S_POD_UID：主機網路 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 建立關聯後，即可將擷取的中繼資料新增至範圍、指標和記錄檔，做為資源屬性。
  • 提示詞和回覆。
    • OTEL_INSTRUMENTATION_GENAI_UPLOAD_FORMAT='jsonl'：指示 OpenTelemetry 將 Cloud Storage 物件格式設為 JSON Lines。這個環境變數的值固定為 jsonl。
    • OTEL_INSTRUMENTATION_GENAI_COMPLETION_HOOK='upload'：指示 OpenTelemetry 上傳提示和回應資料，而不是將這類內容嵌入追蹤範圍。記錄項目會包含上傳物件的參照。這個環境變數的值固定為 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 資料，但不支援其他類型，則 Managed OpenTelemetry for GKE 會收集 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 定價」一文。

配額

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

後續步驟