Google 会使用 AI 技术将内容翻译成您偏好的语言。AI 翻译可能包含错误。

为 GKE 部署托管式 OpenTelemetry

Autopilot Standard

本文档介绍了如何为 GKE 设置 Managed OpenTelemetry，以将 OpenTelemetry 协议 (OTLP) 跟踪记录、指标和日志从 GKE 上运行的应用发送到 Google Cloud Observability。

如需详细了解适用于 GKE 的托管式 OpenTelemetry 的运作方式，请参阅适用于 GKE 的托管式 OpenTelemetry。

您可以使用适用于 GKE 的受管 OpenTelemetry 执行以下操作：

配置在 GKE 上运行的工作负载，以将 OpenTelemetry 协议 (OTLP) 跟踪记录、指标和日志发送到受管收集器。
接收来自在 GKE 上运行的应用的 OpenTelemetry 协议 (OTLP) 跟踪记录、指标和日志。
将该数据导出到 Google Cloud Observability。

如果您需要收集器级过滤和控制，请使用 Google 构建的 OpenTelemetry 收集器，而不是此托管产品。

准备工作

安装 Google Cloud CLI。

注意：如果您之前安装了 gcloud CLI，请确保通过运行 gcloud components update 来获得最新版本。
配置 gcloud CLI 以使用您的联合身份。

如需了解详情，请参阅使用联合身份登录 gcloud CLI。
如需初始化 gcloud CLI，请运行以下命令：
```
gcloud init
```
创建或选择 Google Cloud 项目。
选择或创建项目所需的角色
- 选择项目：选择项目不需要特定的 IAM 角色，您可以选择已获授角色的任何项目。
- 创建项目：如需创建项目，您需要拥有 Project Creator 角色 (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，您需要拥有 Service Usage Admin 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 Cluster Admin (roles/container.clusterAdmin)
Monitoring Viewer (roles/monitoring.viewer)
Logs Viewer (roles/logging.viewer)
Cloud Trace User (roles/cloudtrace.user)

如需详细了解如何授予角色，请参阅管理对项目、文件夹和组织的访问权限。

您也可以通过自定义角色或其他预定义角色来获取所需的权限。

费用

如需详细了解与使用 GKE 的受管 OpenTelemetry 相关的费用，请参阅结算。

在集群中为 GKE 启用托管式 OpenTelemetry

如需为 GKE 设置受管 OpenTelemetry，您需要执行以下操作：

在集群中为 GKE 启用托管式 OpenTelemetry。
配置您要监控的应用，以将信号发送到受管收集器的端点。

为 GKE 启用托管式 OpenTelemetry 后，系统会将以下对象部署到集群：

部署在 gke-managed-otel 命名空间内的 GKE 受管 OpenTelemetry 收集器部署。集群内受管理的 OpenTelemetry 收集器 HTTP 端点（用于日志、指标和轨迹）如下所示：http://opentelemetry-collector.gke-managed-otel.svc.cluster.local:4318。
一种自定义资源定义 (instrumentations.telemetry.googleapis.com)，可用于设置工作负载的自动配置。

如需详细了解自定义资源，请参阅 Kubernetes 文档中的自定义资源。

在新集群上启用

如需在新集群上为 GKE 启用 Managed OpenTelemetry，请按照以下步骤操作：

gcloud

对于 Autopilot 集群，请使用以下命令：

gcloud beta 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：版本，必须为 1.34.1-gke.2178000 或更高版本。

对于 Standard 集群，请使用以下命令：

gcloud beta 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：版本，必须为 1.34.1-gke.2178000 或更高版本。

控制台

对于 Autopilot 集群，请执行以下操作：
1. 在 Google Cloud 控制台中，前往创建 Autopilot 集群页面。
  前往“创建 Autopilot 集群”
2. 在导航面板中，点击高级设置。
3. 在操作部分中，选择启用托管式 OpenTelemetry。
4. 点击保存。
对于 Standard 集群，请执行以下操作：
1. 在 Google Cloud 控制台中，前往创建一个 Kubernetes 集群页面。
  前往“创建一个 Kubernetes 集群”页面
2. 在导航面板中，点击功能。
3. 在操作部分中，选择启用托管式 OpenTelemetry。
4. 点击保存。

Terraform

如需使用 Terraform 在新集群上为 GKE 启用托管式 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"
  }
}

如需详细了解如何使用 Terraform，请参阅针对 GKE 的 Terraform 支持。

在现有集群上启用

如需在现有集群上启用 Managed OpenTelemetry for GKE，请按以下步骤操作：

gcloud

确保集群版本为 1.34.1-gke.2178000 或更高版本。如需详细了解如何升级现有集群，请参阅 Standard 集群升级和 Autopilot 集群升级。

使用以下命令为 GKE 启用托管式 OpenTelemetry：

gcloud beta 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：区域或可用区。

控制台

确保集群版本为 1.34.1-gke.2178000 或更高版本。如需详细了解如何升级现有集群，请参阅 Standard 集群升级和 Autopilot 集群升级。
在 Google Cloud 控制台中，前往“Kubernetes 集群”页面：

转到 Kubernetes 集群
点击集群的名称。
在功能列表中，找到 Managed OpenTelemetry 选项。如果该选项被列为已停用，请点击“修改”图标修改，然后选择启用受管理的 OpenTelemetry。
点击保存更改。

Terraform

如需在现有集群上为 GKE 启用受管理的 OpenTelemetry，请将 managed_opentelemetry_config 块添加到现有 google_container_cluster 资源，如以下示例所示：

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

如需详细了解如何使用 Terraform，请参阅针对 GKE 的 Terraform 支持。

配置应用以使用托管式 OpenTelemetry 收集器

需要配置应用，使其能够将信号发送到受管理的收集器的端点。配置应用后，受管理的 OpenTelemetry 收集器会接收来自集群上运行的应用的信号，而该集群正是启用收集器的集群。来自应用的信号包括跟踪记录、指标和日志。

如需发送 OpenTelemetry 信号，应用需要已插桩，以便生成 OpenTelemetry 指标。如需了解详情，请参阅支持的工作负载。

您可以手动配置应用以将信号发送到受管理的收集器端点，也可以使用自动配置。我们不建议对同一工作负载同时使用这两种方法，因为自动配置可能会覆盖手动更改。这种组合可能会使跟踪配置更改变得更加困难。

以下部分介绍了如何配置应用以使用自动配置向收集器发送信号。

设置自动配置

自动配置使用环境变量来配置工作负载，以将信号发送到受管收集器的端点。

如需启用自动将环境变量注入到 Pod 中，请使用 Instrumentation 自定义资源。环境变量包含 OpenTelemetry 配置，可以注入到命名空间中具有匹配标签的某些 Pod 或命名空间中的所有 Pod。

然后，当应用部署到命名空间时，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 的命名空间。使用 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
```
如需自动注入环境变量，您需要将应用部署到集群中已应用配置的命名空间。
- 如需将配置应用于尚未在命名空间中运行的工作负载，请使用以下命令部署该工作负载：
```
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 中查看这些信号。

如需详细了解如何查看信号，请参阅查看遥测数据。如需查看示例，请参阅生成示例遥测数据。

修改配置

如需修改配置，您需要执行以下操作：

修改 Instrumentation 清单文件。
应用修改后的配置。
应用修改后的配置后，重新部署或重启集群相应命名空间中的应用。

如需详细了解这些步骤，请按照创建和部署配置部分中的说明进行操作。

修改数据收集量或频率

您可以修改轨迹采样率来修改收集的轨迹数据量。

您可以修改指标导出间隔，从而修改监控数据发送到 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 的受管 OpenTelemetry，以收集多模态提示和回答数据。

此功能适用于 LangGraph ReAct 代理和使用智能体开发套件 (ADK) 框架构建的生成式 AI 代理。

如果您使用适用于 GKE 的受管 OpenTelemetry 收集多模态提示和回答数据，系统会收集最终用户的提示和回答的完整内容。这些提示和回答数据存储在 Cloud Storage 存储桶中。如需详细了解如何管理存储桶（包括控制访问权限或删除数据），请参阅 Cloud Storage 文档。

您可以使用 Model Armor 和 Sensitive Data Protection 等产品来管理提示和回答中可能存在的敏感数据。

如需配置适用于 GKE 的受管 OpenTelemetry 以收集多模态提示和回答数据，请执行以下操作：

按照收集多模态提示和回答部分中的说明，配置您的 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 的命名空间。

如需暂时停用自动环境变量注入，同时保留自动插桩配置以供日后使用，请将 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：命名空间。

查看遥测数据

当配置的工作负载在启用了 Managed OpenTelemetry for GKE 的 GKE 上运行时，OpenTelemetry 信号会发送到 Google Cloud Observability。

如需详细了解如何在 Google Cloud Observability 中查看数据，请参阅以下内容：

生成示例遥测数据

本部分介绍如何部署一个示例应用并将该应用指向受管理的 OpenTelemetry 收集器的 OTLP 端点。然后，您可以在 Google Cloud中查看遥测数据。

示例应用是一个小型生成器，用于将跟踪记录、日志和指标导出到集群内受管理的 OpenTelemetry 收集器 HTTP 端点。OTLP 端点已在应用中硬编码，指向 http://opentelemetry-collector.gke-managed-otel.svc.cluster.local:4318。

如果您已有使用 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. 按 span 名称等于 lets-go 过滤轨迹 span。
4. 如需查看日志，请执行以下操作：
  1. 在 Google Cloud 控制台中，转到 Logs Explorer 页面。
    
    转到 Logs Explorer
  2. 请运行以下查询：
```
resource.type="k8s_pod"
resource.labels.namespace_name="opentelemetry-demo"
```

为 GKE 停用托管式 OpenTelemetry

您可以在集群中停用 GKE 的托管式 OpenTelemetry。停用收集器后，系统会从集群中移除受管理的 OpenTelemetry 收集器，并且不会再收集新的遥测数据。

如需停用 GKE 的受管 OpenTelemetry，请按以下步骤操作。

gcloud

如需为集群停用 GKE 的受管 OpenTelemetry，请运行以下 gcloud 命令：

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

替换以下内容：

CLUSTER_NAME：集群的名称。
PROJECT_ID： Google Cloud 项目 ID。
LOCATION：区域或可用区。

控制台

在控制台中，前往集群列表：

转到 Kubernetes 集群
选择要停用受管 OpenTelemetry 收集器的集群。
在集群详情中，选择托管式 OpenTelemetry 旁边的修改图标。
清除相应复选框即可停用此功能。

Terraform

如需停用 GKE 的受管 OpenTelemetry，请更新 google_container_cluster 资源中的 managed_opentelemetry_config 块，将范围设置为 NONE。

更新您的 Terraform 配置文件：

resource "google_container_cluster" "default" {
  provider = google-beta
  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 的受管 OpenTelemetry 时，系统不会从集群中移除 Instrumentation 自定义资源定义和 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 自定义资源已正确配置，其命名空间与工作负载运行的命名空间一致，并且选择器与工作负载的标签一致。
检查工作负载的 Pod，看看环境变量是否已正确注入。
检查 OpenTelemetry 收集器的容器日志，看看收集器中是否存在错误。为此，请运行以下命令：
```
kubectl logs -n gke-managed-otel -l app=opentelemetry-collector -c opentelemetry-collector
```

停用遥测信号不起作用

使用 Instrumentation 自定义资源停用遥测信号时，请确保应用该自定义资源并重新部署工作负载。

应用自定义资源时，在更新 Instrumentation 自定义资源时，请在 kubectl apply 命令中使用 Server-Side Apply。

如需详细了解如何停用遥测信号，请参阅选择要收集的信号类型。

OpenTelemetry 注入的变量在我的工作负载中不可见

变量会注入到工作负载 Pod 的容器中，而不是工作负载本身。检查 Pod，而不是 ReplicaSet 或 Deployment 等所有者对象。

例如，如需确认变量是否已为上一部分生成遥测数据中使用的默认命名空间中的示例工作负载正确注入，请执行以下操作：

运行以下命令：

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

检查 Pod 的 spec.containers[*].env。
确保同一命名空间中存在 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 行为是“始终开启”跟踪，相当于比率为 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 的运作方式，请参阅 GKE 的托管式 OpenTelemetry。
如需了解 GKE 的托管式 OpenTelemetry 的自行部署替代方案，请参阅 Google 构建的 OpenTelemetry 收集器。

为 GKE 部署托管式 OpenTelemetry 使用集合让一切井井有条 根据您的偏好保存内容并对其进行分类。

准备工作

要求

所需的角色

费用

在集群中为 GKE 启用托管式 OpenTelemetry

在新集群上启用

gcloud

控制台

Terraform

在现有集群上启用

gcloud

控制台

Terraform

配置应用以使用托管式 OpenTelemetry 收集器

设置自动配置

修改配置

修改数据收集量或频率

修改轨迹采样率

修改指标导出间隔

选择要收集的信号类型

收集多模态提示和回答数据

停用工作负载的自动配置

查看遥测数据

生成示例遥测数据

为 GKE 停用托管式 OpenTelemetry

gcloud

控制台

Terraform

问题排查

Autopilot 合作伙伴特权工作负载

日志、指标或轨迹未显示在 Google Cloud 控制台中

停用遥测信号不起作用

OpenTelemetry 注入的变量在我的工作负载中不可见

Cloud Trace 中的跟踪数据过多

环境变量与配置不匹配

kubectl logs 命令不返回任何输出

后续步骤

为 GKE 部署托管式 OpenTelemetry

`kubectl logs` 命令不返回任何输出