部署 GKE 適用的代管 OpenTelemetry

本文說明如何為 GKE 設定代管 OpenTelemetry，從 GKE 上執行的應用程式，將 OpenTelemetry Protocol (OTLP) 追蹤記錄、指標和記錄傳送至 Google Cloud Observability。

如要進一步瞭解 GKE 適用的代管 OpenTelemetry 運作方式，請參閱「GKE 適用的代管 OpenTelemetry」。

您可以使用 GKE 適用的 Managed OpenTelemetry 執行下列操作：

• 設定在 GKE 上執行的工作負載，將 OpenTelemetry Protocol (OTLP) 追蹤記錄、指標和記錄傳送至代管收集器。
• 接收來自 GKE 執行應用程式的 OpenTelemetry Protocol (OTLP) 追蹤記錄、指標和記錄。
• 將資料匯出至 Google Cloud Observability。

如需收集器層級的篩選和控制項，請改用 Google 打造的 OpenTelemetry Collector，而非這項代管服務。

事前準備

登入 Google Cloud 帳戶。如果您是 Google Cloud新手，歡迎 建立帳戶，親自評估產品在實際工作環境中的成效。新客戶還能獲得價值 $300 美元的免費抵免額，可用於執行、測試及部署工作負載。

安裝 Google Cloud CLI。

若您採用的是外部識別資訊提供者 (IdP)，請先使用聯合身分登入 gcloud CLI。

執行下列指令，初始化 gcloud CLI：

gcloud init

建立或選取 Google Cloud 專案。

選取或建立專案所需的角色

• 選取專案：選取專案時，不需要具備特定 IAM 角色，只要您在專案中獲派角色，即可選取該專案。
• 建立專案：如要建立專案，您需要專案建立者角色 (roles/resourcemanager.projectCreator)，其中包含 resourcemanager.projects.create 權限。瞭解如何授予角色。

• 建立 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、遙測 (OTLP)、Cloud Logging、Cloud Monitoring、Cloud Trace API：

啟用 API 時所需的角色

如要啟用 API，您需要具備服務使用情形管理員 IAM 角色 (roles/serviceusage.serviceUsageAdmin)，其中包含 serviceusage.services.enable 權限。瞭解如何授予角色。

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

安裝 Google Cloud CLI。

若您採用的是外部識別資訊提供者 (IdP)，請先使用聯合身分登入 gcloud CLI。

執行下列指令，初始化 gcloud CLI：

gcloud init

建立或選取 Google Cloud 專案。

選取或建立專案所需的角色

• 選取專案：選取專案時，不需要具備特定 IAM 角色，只要您在專案中獲派角色，即可選取該專案。
• 建立專案：如要建立專案，您需要專案建立者角色 (roles/resourcemanager.projectCreator)，其中包含 resourcemanager.projects.create 權限。瞭解如何授予角色。

• 建立 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、遙測 (OTLP)、Cloud Logging、Cloud Monitoring、Cloud Trace API：

啟用 API 時所需的角色

如要啟用 API，您需要具備服務使用情形管理員 IAM 角色 (roles/serviceusage.serviceUsageAdmin)，其中包含 serviceusage.services.enable 權限。瞭解如何授予角色。

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 以上版本。
• 啟用 gcloud CLI 551.0.0 以上版本。
• 如果您使用 Terraform 佈建 GKE 基礎架構，請務必使用 terraform-provider-google-beta 供應程式 v7.17.0 以上版本。

必要的角色

如要取得啟用及使用 GKE 管理的 OpenTelemetry 所需的權限，請要求管理員在專案中授予您下列 IAM 角色：

• Kubernetes Engine 叢集管理員 (roles/container.clusterAdmin)
• Monitoring 檢視者 (roles/monitoring.viewer)
• 記錄檢視器 (roles/logging.viewer)
• Cloud Trace 使用者 (roles/cloudtrace.user)

如要進一步瞭解如何授予角色，請參閱「管理專案、資料夾和組織的存取權」。

您或許也能透過自訂角色或其他預先定義的角色，取得必要權限。

費用

如要進一步瞭解使用 GKE 代管 OpenTelemetry 的相關費用，請參閱「帳單」。

在叢集中啟用 GKE 適用的代管 OpenTelemetry

如要為 GKE 設定代管 OpenTelemetry，請完成下列步驟：

• 在叢集中啟用 GKE 的代管 OpenTelemetry。
• 設定要監控的應用程式，將信號傳送至受管理收集器的端點。

為 GKE 啟用代管 OpenTelemetry 時，系統會將下列物件部署至叢集：

• 部署在 gke-managed-otel 命名空間中的 GKE Managed OpenTelemetry 收集器部署作業。叢集內受管理 OpenTelemetry 收集器記錄、指標和追蹤記錄的 HTTP 端點如下：http://opentelemetry-collector.gke-managed-otel.svc.cluster.local:4318。

• 自訂資源定義 instrumentations.telemetry.googleapis.com，可用於設定工作負載的自動設定。

  如要進一步瞭解自訂資源，請參閱 Kubernetes 說明文件中的「自訂資源」。

在新叢集上啟用

如要為新叢集啟用 GKE 代管 OpenTelemetry，請按照下列步驟操作：

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

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

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"
  }
}

在現有叢集上啟用

如要在現有叢集上啟用 GKE 適用的 Managed OpenTelemetry，請按照下列步驟操作：

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"
  }
}

設定應用程式以使用代管 OpenTelemetry 收集器

應用程式必須經過設定，才能將信號傳送至受管理收集器的端點。設定應用程式後，代管 OpenTelemetry 收集器會接收來自叢集上執行應用程式的信號，而收集器也會在該叢集上啟用。應用程式的信號包括追蹤記錄、指標和記錄檔。

如要傳送 OpenTelemetry 信號，應用程式必須已檢測完畢，才能產生 OpenTelemetry 指標。詳情請參閱「支援的工作負載」。

您可以手動設定應用程式，將信號傳送至受管理的收集器端點，也可以使用自動設定。我們不建議對相同工作負載同時使用這兩種方法，因為自動設定可能會覆寫手動變更。這樣一來，您可能就更難追蹤設定的變更。

以下各節說明如何設定應用程式，透過自動設定將信號傳送至收集器。

設定自動設定

自動設定會使用環境變數，將工作負載設定為將信號傳送至受管理收集器的端點。

如要啟用環境變數自動注入 Pod 的功能，請使用 Instrumentation 自訂資源。環境變數包含 OpenTelemetry 設定，且可注入命名空間中具有相符標籤的部分 Pod，或命名空間中的所有 Pod。

然後，當應用程式部署至命名空間時，GKE 會使用這項設定，自動將環境變數注入工作負載執行的 Pod。

1. 如要設定 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 的命名空間。使用 default 指定預設命名空間。
      • NAME：資訊清單檔案名稱。在本範例中，名稱為 otlp-auto-config-namespace.yaml。
      • (選用) 附加至 Pod 的標籤，用於指定目標。如果指定空白選取器 ({})，系統會以命名空間中的所有 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
      

2. 如要自動插入環境變數，您必須將應用程式部署至叢集中的命名空間，並套用設定。

   • 如要將設定套用至尚未在命名空間中執行的工作負載，請使用下列指令部署工作負載：

     kubectl apply -f DEPLOYMENT_NAME -n NAMESPACE
     

     更改下列內容：

     • DEPLOYMENT_NAME：部署作業的名稱。
     • NAMESPACE：命名空間。

   • 如要將設定套用至命名空間中已在執行的工作負載，請使用下列指令重新部署工作負載：

     kubectl rollout restart deployment DEPLOYMENT_NAME -n NAMESPACE
     

     更改下列內容：

     • DEPLOYMENT_NAME：部署作業的名稱。
     • NAMESPACE：命名空間。

將設定套用至叢集後，GKE 會在工作負載部署至叢集時，自動設定所有工作負載。方法是將環境變數插入工作負載執行的 Pod，藉此檢測工作負載。

如果工作負載已設定這些環境變數，且在部署代管收集器的叢集中執行，工作負載就會在執行時將 OpenTelemetry 信號傳送至代管收集器。您可以在 Google Cloud Observability 中查看這些信號。

如要進一步瞭解如何查看信號，請參閱「查看遙測資料」。如需範例，請參閱「產生遙測資料範例」。

修改設定

如要修改設定，請按照下列步驟操作：

1. 修改 Instrumentation 資訊清單檔案。

2. 套用修改後的設定。

3. 套用修改後的設定後，請在叢集的對應命名空間中重新部署或重新啟動應用程式。

如要進一步瞭解這些步驟，請按照「建立及部署設定」一節中的操作說明進行。

修改資料收集量或頻率

您可以修改追蹤取樣率，調整收集的追蹤資料量。

您可以修改指標匯出間隔，調整監控資料傳送至 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 連續匯出指標時，兩次匯出之間的延遲間隔。

這個間隔的值必須為非負數，最小值為 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 適用的 Managed OpenTelemetry，收集多模態提示和回應資料。

這項功能適用於 LangGraph ReAct 代理，以及使用 Agent Development Kit (ADK) 架構建構的生成式 AI 代理。

使用 GKE 適用的 Managed OpenTelemetry 收集多模態提示和回覆資料時，系統會收集使用者提示和回覆的完整內容。系統會將提示和回覆資料儲存在 Cloud Storage 值區中。如要瞭解如何管理儲存空間值區，包括控管存取權或刪除資料，請參閱 Cloud Storage 說明文件。

您可以運用 Model Armor 和 Sensitive Data Protection 等產品，管理提示和回覆中可能出現的私密/機密資料。

如要設定 GKE 適用的 Managed OpenTelemetry，以收集多模態提示和回應資料，請按照下列步驟操作：

1. 按照「收集多模態提示和回應」一節的說明，設定專案和使用的 SDK。 Google Cloud

2. 建立或找出要用來收集多模態提示詞和回覆的 Cloud Storage bucket。詳情請參閱「建立值區」一節。

3. 授予應用程式使用的服務帳戶 Cloud Storage bucket 的 storage.objects.create 權限。

   這項權限可讓應用程式將物件寫入 Cloud Storage 值區。這些物件會儲存代理程式應用程式建立及接收的提示和回覆。詳情請參閱「在 bucket 上設定及管理 IAM 政策」。

4. 在 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 的命名空間。

如要暫時停用自動環境變數插入功能，同時保留自動檢測設定供日後使用，請將 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：命名空間。

查看遙測資料

當設定的工作負載在已啟用 GKE 代管 OpenTelemetry 的 GKE 上執行時，OpenTelemetry 訊號會傳送至 Google Cloud Observability。

如要瞭解如何在 Google Cloud Observability 中查看資料，請參閱下列文章：

• 尋找及探索追蹤記錄。
• 使用 Metrics Explorer 建立圖表。
• 查看及分析記錄。

產生遙測資料範例

本節說明如何部署範例應用程式，並將該應用程式指向 Managed OpenTelemetry 收集器的 OTLP 端點。接著，您就可以在 Google Cloud中查看遙測資料。

這個範例應用程式是小型產生器，可將追蹤記錄、記錄和指標匯出至叢集內代管 OpenTelemetry 收集器的 HTTP 端點。OTLP 端點已在應用程式中以硬式編碼方式寫死，指向 http://opentelemetry-collector.gke-managed-otel.svc.cluster.local:4318。

如果您已使用 OpenTelemetry SDK 檢測應用程式，可以將應用程式指向收集器的端點，或為應用程式設定自動檢測，從應用程式產生遙測資料。

如要部署範例應用程式，請按照下列步驟操作：

1. 連線至已啟用代管 OpenTelemetry 的叢集。如要這麼做，請參閱「設定 kubectl 指令的預設叢集」。

2. 執行下列指令：

   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. 在指標探索器中執行下列 PromQL 查詢：

         sum(avg_over_time({"__name__"="gen","namespace"="opentelemetry-demo","job"="telemetrygen"}[1h]))
         

   3. 如要查看追蹤記錄，請按照下列步驟操作：

      1. 前往 Google Cloud 控制台的「Trace Explorer」頁面。

         前往「Trace Explorer」

      2. 篩選時距名稱等於 lets-go 的追蹤記錄時距。

   4. 如要查看記錄，請按照下列步驟操作：

      1. 前往 Google Cloud 控制台的「Logs Explorer」頁面。

         前往「Logs Explorer」頁面

      2. 執行以下查詢：

         resource.type="k8s_pod"
         resource.labels.namespace_name="opentelemetry-demo"
         

停用 GKE 的代管 OpenTelemetry

您可以在叢集中停用 GKE 的代管 OpenTelemetry。 停用收集器後，系統會從叢集中移除 Managed OpenTelemetry 收集器，並停止收集新的遙測資料。

如要停用 GKE 適用的 Managed OpenTelemetry，請按照下列步驟操作。

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

停用 GKE 適用的 Managed OpenTelemetry 時，Instrumentation自訂資源定義和Instrumentation自訂資源不會從叢集中移除。如果重新啟用代管 OpenTelemetry，系統會使用 Instrumentation 自訂資源中保留的設定。

如果 Managed OpenTelemetry for GKE 已收集遙測資料，停用收集器不會影響這些資料。現有資料仍會儲存在 Google Cloud Observability 中，但系統不會收集新的遙測資料。

疑難排解

Autopilot 合作夥伴專屬工作負載

如果您嘗試使用自動設定功能，搭配 Autopilot 合作夥伴的具備權限工作負載，可能會發現該工作負載 Pod 遭到拒絕。

OpenTelemetry 設定注入功能不支援來自 GKE Autopilot 合作夥伴的具備特殊權限工作負載。使用 Instrumentation 自訂資源指定這類工作負載，以啟用 OpenTelemetry 環境變數注入功能，可能會導致工作負載無法與 Autopilot 具備特殊權限的工作負載許可清單相符，也就是說，GKE Autopilot 會拒絕注入設定的 Pod。

Google Cloud 控制台未顯示記錄、指標或追蹤記錄

無法查看資料的原因有很多。原因包括缺少資料檢視權限，或是設定有誤導致系統無法收集資料。

如要解決常見問題，請按照下列步驟操作：

• 確認專案已啟用所有必要 API。

• 請確認Instrumentation自訂資源設定正確無誤，且命名空間與工作負載執行的命名空間相符，選取器也與工作負載的標籤相符。

• 檢查工作負載的 Pod，確認環境變數是否已正確注入。

• 檢查 OpenTelemetry 收集器容器記錄，確認收集器是否發生錯誤。如要進行此操作，請執行以下指令：

  kubectl logs -n gke-managed-otel -l app=opentelemetry-collector -c opentelemetry-collector
  

無法停用遙測信號

使用 Instrumentation 自訂資源停用遙測信號時，請務必套用自訂資源，並重新部署工作負載。

套用自訂資源時，請在更新 Instrumentation 自訂資源時，使用 kubectl apply 指令中的「伺服器端套用」。

如要瞭解如何停用遙測信號，請參閱「選取要收集的信號類型」。

OpenTelemetry 插入的變數不會顯示在工作負載中

變數會注入工作負載 Pod 的容器，而非工作負載。請檢查 Pod，而非 ReplicaSet 或 Deployment 等擁有者物件。

舉例來說，如要確認變數是否已正確注入前一節「產生遙測資料」中使用的預設命名空間範例工作負載，請按照下列步驟操作：

1. 執行下列指令：

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

2. 檢查 Pod 的 spec.containers[*].env。

3. 確認相同命名空間中是否有 Instrumentation 物件，並檢查該物件是否以 Pod 為目標，且已啟用設定注入功能。如要進行此操作，請執行以下指令：

   kubectl get instrumentations.telemetry.googleapis.com -n default -o yaml
   

只有在建立 Pod 時，變數才會注入容器，因為 Kubernetes API 不允許修改現有 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 的設定有誤，請確認 Instrumentation 物件是否正確指定 Pod，以及您是否有多個 Instrumentation 物件指定同一個 Pod：

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

請注意，空白選取器會以命名空間中的所有 Pod 為目標。

如果多個插樁在建立時以同一個 Pod 為目標，則最後更新的插樁會生效。

kubectl logs 指令不會傳回任何輸出內容

如果記錄直接從應用程式串流至 OpenTelemetry 收集器，記錄就會略過容器執行階段的標準記錄路徑。這是使用 OpenTelemetry 記錄檔時的常見情境。根據預設，匯出工具會將記錄傳送至 otlp 端點，而不是 stdout 和 stderr 串流。

在本例中，由於記錄不會寫入 stdout 或 stderr 串流，供容器執行階段擷取，因此 kubectl logs 指令不會顯示該應用程式的任何輸出內容。而是透過 Cloud Logging 輸出記錄。

如要使用 OpenTelemetry SDK，並將記錄傳送至 stdout 串流，請使用記錄匯出器進行設定。詳情請參閱「記錄匯出工具 - 標準輸出」。

後續步驟

• 如要瞭解 GKE 適用的代管 OpenTelemetry 運作方式，請參閱這篇文章。
• 如要自行部署代管 OpenTelemetry for GKE 的替代方案，請參閱 Google 建構的 OpenTelemetry 收集器。