本文档采用自动化机器翻译技术翻译。尽管我们力求提供准确的译文，但不对翻译内容的完整性、准确性或可靠性作出任何保证。若出现任何内容不一致情况，请以原始英文版本为准，且原始英文版本为权威文本。

故障排除 OpenTelemetry

有很多配置选项，但更重要的是，每个 (Kubernetes) 环境略有不同。要快速找出问题所在，最简单的方法是选择一个预期会有遥测数据的 pod：

检查 pod 日志开头，SDK 在启动时会记录警告或错误，以表明仪器化失败。
检查日志中是否有与发送数据到收集器相关的错误。
检查收集器 pod 的日志，查看配置或初始化错误，这些错误会在 pod 启动后立即记录。
检查收集器日志中是否有与发送数据到 SUSE Observability 相关的错误。

日志中的错误通常能很好地指示问题所在。我们列出了 OpenTelemetry 数据在某些或所有已接入遥测的应用程序中不可用的最常见原因。如果这里没有列出问题，您还可以查看特定语言的 SDK 文档或 OpenTelemetry 的收集器文档。

使用相同的 Kubernetes 集群名称

确保在以下情况下为同一集群使用相同的 Kubernetes 集群名称：

安装 Open Telemetry Collector
安装 SUSE Observability 代理
安装 Kubernetes StackPack

当为同一集群使用不同名称时，SUSE Observability 将无法将 Open Telemetry 的数据与 SUSE Observability 代理的数据匹配，跟踪视图将保持为空。

收集器无法将数据发送到 SUSE Observability

SUSE Observability 的 OTLP 端点和 API 密钥配置错误

如果出现连接错误，可能是 OTLP 端点不正确。如果出现身份验证/授权错误（状态代码 401 和 403），则可能 API 密钥不再有效。检查配置的 OTLP 端点是否是您的 SUSE Observability 的 URL，前面加上 otlp-，后面加上 :443。例如，play.stackstate.com 的 OTLP 端点是 otlp-play.stackstate.com:443。

为了确保 API 密钥配置正确，请检查：

密钥包含有效的 API 密钥（在 SUSE Observability 中验证此项）
该密钥在 pod 上用作环境变量。
bearertokenauth 扩展使用正确的方案和来自 API_KEY 环境变量的值
bearertokenauth 扩展被 otlp/suse-observability 导出器使用

某些代理和防火墙与 gRPC 的兼容性不好

如果收集器需要通过代理或防火墙将数据发送到 SUSE Observability，可能会完全阻止流量，或者可能会丢失 gRPC 消息的某些部分，或者意外地完全中断长期的 gRPC 连接。最简单的解决方法是将 gRPC 切换为使用 HTTP，通过将 otlp/suse-observability 导出器配置 和管道部分中的引用 替换为 otlphttp/suse-observability 导出器。

这里 <otlp-http-suse-observability-endpoint> 类似于 <otlp-suse-observability-endpoint>，但它的前缀是 otlp-http-，而不是 otlp- 前缀，例如，otlp-http-play.stackstate.com。有关更多详细信息，请参见收集器配置。

被监控的应用程序无法将数据发送到收集器

URL 不正确或流量被阻止

如果 SDK 记录错误，提示无法解析收集器 DNS 名称，可能是配置的收集器 URL 不正确。在 Kubernetes 中，您的应用程序通常部署在与收集器不同的名称空间中。这意味着 SDK 需要使用收集器服务的完全限定的域名进行配置：http://<service-name>.<namespace>.svc.cluster.local:4317。在收集器安装步骤中，这是 http://opentelemetry-collector.open-telemetry.svc.cluster.local:4317，但如果您为收集器使用了不同的名称空间或发布名称，则可能与您的情况不同。

如果 SDK 记录网络连接超时，可能是收集器配置错误或使用了错误的端口。但也有可能 Kubernetes 网络策略阻止了您的应用程序与收集器之间的网络流量。这最好由您的 Kubernetes 管理员来验证。网络策略至少应允许来自您所有应用程序到收集器的配置端口（4317 和/或 4318）的 TCP 流量。

语言 SDK 不支持 gRPC。

并非所有语言 SDK 都支持 gRPC。如果不支持通过 gRPC 的 OTLP，最好切换到通过 HTTP 的 OTLP。SDK 导出器配置描述了如何进行此切换。

语言 SDK 使用了错误的端口。

使用错误的端口通常会表现为连接错误，但也可能表现为网络连接意外关闭。确保 SDK 导出器在发送数据时使用正确的端口。请参见 SDK 导出器配置。

启用 hostNetwork 的 Kubernetes pod。

Open Telemetry 收集器使用 Kubernetes 元数据丰富遥测数据。按照配置，所有无法丰富的遥测数据将被丢弃。然而，收集器无法丰富自动设置为 hostNetwork: true 的 pod。这是不可能的，因为 pod 的识别是通过 pod 的 IP 地址进行的，而使用主机网络的 pod 使用的是主机的 IP 地址。

为了帮助收集器识别 pod，我们可以指示 SDK 直接在元数据中添加 k8s.pod.uid 属性。为此，请修改您的 pod 规格，并将以下环境变量添加到您的应用程序容器中：

env:
  - name: POD_UID
    valueFrom:
      fieldRef:
        apiVersion: v1
        fieldPath: metadata.uid
  - name: OTEL_RESOURCE_ATTRIBUTES
    value: k8s.pod.uid=$(POD_UID)

如果 OTEL_RESOURCE_ATTRIBUTES 环境变量已经设置，只需添加 k8s.pod.uid，使用逗号作为分隔符。该值是一个以逗号分隔的列表。

在 Google Kubernetes Engine 上的 Node.js 应用程序。

Node.js SDK 仅在 GKE 上，期望 Kubernetes 的名称空间通过 NAMESPACE 环境变量设置。如果未设置，它仍会添加 k8s.namespace.name 属性，但值为空。这会阻止 Kubernetes 属性处理器插入正确的名称空间名称。在此修复之前，解决方法是更新您的 pod 规格，并将此环境变量添加到容器中：

env:
  - name: NAMESPACE
    valueFrom:
      fieldRef:
        apiVersion: v1
        fieldPath: metadata.namespace

Node.js 应用程序没有可用的指标

通过环境变量配置的 Node.js 自动仪器化仅支持跟踪。至少在此 Open Telemetry 问题解决之前。要启用自动仪器化生成的指标，需要进行代码更改。请按照 Open Telemetry 文档中的说明进行这些更改。

无法添加 Kubernetes 属性

在收集器安装期间，会在 Kubernetes 中创建集群角色和集群角色绑定，允许收集器读取 Kubernetes 资源的元数据。如果此操作失败或被删除，收集器将无法再查询 Kubernetes API。这将在收集器日志中显示为错误，错误包括无法检索元数据的资源类型。

要修复此问题，请使用 Helm 图表重新安装收集器，并确保您拥有创建集群角色和集群角色绑定所需的权限。或者，请求您的集群管理员以所需权限进行收集器安装。