#仪表化故障排除

在使用 OpenTelemetry 仪表化时，您可能会遇到两类主要问题：仪表化未能成功注入到工作负载中，以及仪表化库未能正确生成遥测数据。本文档提供了针对这两类问题的故障排除方法。

#概述

仪表化故障排除主要关注以下方面：

• 注入问题：仪表化是否成功注入到应用 Pod 中
• 数据生成问题：仪表化库是否正确生成并发送遥测数据

#故障排除仪表化注入到工作负载

当仪表化未能正确注入到工作负载时，可以通过以下检查步骤诊断问题。

#检查 Instrumentation 对象

首先确认 Instrumentation 对象是否成功创建：

kubectl get instrumentation -n <workload_namespace>

如果未看到预期的 Instrumentation 对象，请检查：

1. Instrumentation 资源是否正确创建
2. 命名空间是否正确
3. Operator 日志中是否有错误信息

#检查 init-container

确认 opentelemetry-auto-instrumentation init-container 是否启动成功：

kubectl get events -n <workload_namespace>

查看 Pod 详细信息：

kubectl describe pod <pod_name> -n <workload_namespace>

在输出中查找 init-container 部分，确认：

• init-container 是否存在
• init-container 是否成功完成
• 是否有错误或警告信息

#检查资源部署顺序

确保资源按正确顺序部署：

1. 先部署 Instrumentation 对象
2. 再部署或重启应用 Pod

如果应用 Pod 在 Instrumentation 对象之前创建，仪表化将不会被注入。此时需要重启 Pod：

kubectl rollout restart deployment <deployment_name> -n <workload_namespace>

#在 Operator 日志中搜索错误

检查 Operator 日志中与仪表化相关的错误：

kubectl logs -l app.kubernetes.io/name=opentelemetry-operator -n opentelemetry-operator2 --tail=100

常见错误包括：

• 配置校验失败
• 权限不足
• 资源冲突

#验证 Pod 注解

确认应用 Pod 具有正确的仪表化注解：

kubectl get pod <pod_name> -n <workload_namespace> -o jsonpath='{.metadata.annotations}' | jq

应看到类似如下的注解：

{
  ...
  "instrumentation.opentelemetry.io/inject-java": "true"
  ...
}

如果注解缺失或不正确：

1. 检查 Deployment 或 Pod 模板中的注解配置
2. 确认注解的命名空间和语言类型是否正确
3. 验证 Instrumentation 对象配置

#检查注入的环境变量

确认仪表化是否正确注入了环境变量：

kubectl exec <pod_name> -n <workload_namespace> -- env | grep OTEL

应看到与 OpenTelemetry 相关的环境变量，例如：

OTEL_SERVICE_NAME=my-service
OTEL_EXPORTER_OTLP_ENDPOINT=http://otel-collector:4317
OTEL_RESOURCE_ATTRIBUTES=service.name=my-service

#验证仪表化库

检查容器内是否正确安装了仪表化库：

kubectl exec <pod_name> -n <workload_namespace> -- sh -c 'ls -lh /otel-auto-instrumentation-*'

该目录应包含仪表化库及相关文件。

#故障排除仪表化库生成遥测数据

如果仪表化成功注入但未生成遥测数据，可以通过以下方法排查。

#验证端点配置

确认仪表化是否将数据发送到正确的端点：

kubectl get instrumentation <instrumentation_name> -n <workload_namespace> -o jsonpath='{.spec.exporter.endpoint}'

示例输出

http://otel-collector:4317

kubectl get instrumentation <instrumentation_name> -n <workload_namespace> -o yaml | grep -A 1 'OTEL_'

默认端点为 http://localhost:4317。如果使用自定义 Collector 端点，请确保：

1. 端点地址正确
2. Collector Service 可访问
3. 端口配置正确（gRPC 使用 4317，HTTP 使用 4318）

#检查应用日志中的错误

检查应用日志中是否有与仪表化相关的错误信息：

kubectl logs <application_pod> -n <workload_namespace>

查找 OpenTelemetry 相关错误，如：

• 连接失败
• 认证错误
• 配置错误
• 库加载失败

#验证 Collector 是否接收数据

确认 Collector 是否接收到遥测数据：

检查 Collector 日志

kubectl logs <collector_pod> -n opentelemetry-collector

如果启用了 Debug Exporter，应能看到接收的数据。

检查 Collector 指标

kubectl port-forward -n opentelemetry-collector <collector_pod> 8888:8888

然后访问 http://localhost:8888/metrics，查看：

• otelcol_receiver_accepted_spans：应大于 0
• otelcol_receiver_refused_spans：应为 0 或非常小