故障排查

本文档提供了 OpenTelemetry Operator 的故障排查指南，帮助您诊断和解决在使用 Operator 时遇到的常见问题。包括 Operator 本身的问题、自动注入问题、HPA 问题、Target Allocator 问题等。

概述

故障排查方法

当遇到问题时，建议按以下步骤进行排查：

1. 收集信息：收集相关的日志、事件和配置信息
2. 检查状态：检查相关资源的状态
3. 分析日志：分析 Operator、Collector 和其他组件的日志
4. 验证配置：验证配置是否正确
5. 测试修复：应用修复并验证

常用命令

以下命令在故障排查中经常使用：

# 检查资源状态
kubectl get <resource-type> -n <namespace>

# 查看资源详细信息
kubectl describe <resource-type> <resource-name> -n <namespace>

# 查看日志
kubectl logs <pod-name> -n <namespace>

# 查看事件
kubectl get events -n <namespace> --sort-by='.lastTimestamp'

# 进入 Pod 调试
kubectl exec -it <pod-name> -n <namespace> -- /bin/sh

Operator 常见问题

1. Operator 无法启动

症状

# Operator Pod 处于 CrashLoopBackOff 状态
kubectl get pods -n opentelemetry-operator-system
# NAME                                                  READY   STATUS             RESTARTS   AGE
# opentelemetry-operator-controller-manager-xxxxx      0/2     CrashLoopBackOff   5          10m

诊断步骤

# 1. 查看 Operator Pod 状态
kubectl describe pod -n opentelemetry-operator-system -l app.kubernetes.io/name=opentelemetry-operator

# 2. 查看 Operator 日志
kubectl logs -n opentelemetry-operator-system -l app.kubernetes.io/name=opentelemetry-operator --tail=100

# 3. 检查事件
kubectl get events -n opentelemetry-operator-system --sort-by='.lastTimestamp'

常见原因和解决方法

原因 1：cert-manager 未安装

# 检查 cert-manager
kubectl get pods -n cert-manager

# 如果未安装，安装 cert-manager
kubectl apply -f https://github.com/cert-manager/cert-manager/releases/latest/download/cert-manager.yaml

原因 2：权限不足

# 检查 ServiceAccount 和 ClusterRoleBinding
kubectl get clusterrolebinding | grep opentelemetry
kubectl get serviceaccount -n opentelemetry-operator-system

# 如果缺失，重新安装 Operator
kubectl apply -f https://github.com/open-telemetry/opentelemetry-operator/releases/latest/download/opentelemetry-operator.yaml

原因 3：镜像拉取失败

# 检查镜像拉取错误
kubectl describe pod -n opentelemetry-operator-system -l app.kubernetes.io/name=opentelemetry-operator | grep -i "image\|pull"

# 解决方法：配置镜像仓库或使用代理

2. Collector 无法创建

症状

# OpenTelemetryCollector 资源存在，但没有创建 Pod
kubectl get opentelemetrycollector
# NAME      MODE         STATUS    AGE
# otelcol   deployment   Pending   5m

kubectl get pods -l app.kubernetes.io/name=opentelemetry-collector
# No resources found

诊断步骤

# 1. 查看 OpenTelemetryCollector 详细信息
kubectl describe opentelemetrycollector <name> -n <namespace>

# 2. 查看 Operator 日志
kubectl logs -n opentelemetry-operator-system -l app.kubernetes.io/name=opentelemetry-operator --tail=100 | grep -i <collector-name>

# 3. 检查事件
kubectl get events -n <namespace> --sort-by='.lastTimestamp' | grep -i collector

常见原因和解决方法

原因 1：配置错误

# 检查配置语法
kubectl get opentelemetrycollector <name> -o yaml | grep -A 50 "config:"

# 验证 YAML 语法
# 使用在线 YAML 验证工具或本地工具验证

原因 2：资源不足

# 检查节点资源
kubectl top nodes

# 检查 Pod 调度状态
kubectl get pods -l app.kubernetes.io/name=opentelemetry-collector -o wide

# 查看调度事件
kubectl describe pod <pod-name> | grep -i "events\|warning"

原因 3：镜像拉取失败

# 检查镜像配置
kubectl get opentelemetrycollector <name> -o yaml | grep image

# 检查镜像是否存在
# 尝试手动拉取镜像

3. 配置验证失败

症状

# Operator 日志显示配置验证错误
kubectl logs -n opentelemetry-operator-system -l app.kubernetes.io/name=opentelemetry-operator | grep -i "error\|invalid"

诊断步骤

# 1. 获取 Collector 配置
kubectl get opentelemetrycollector <name> -o yaml > collector-config.yaml

# 2. 提取 config 字段
# 手动验证 YAML 语法

# 3. 检查 Collector 配置格式
# 确保 receivers、processors、exporters、service 配置正确

常见配置错误

错误 1：YAML 语法错误

# 错误：缺少缩进
config: |
receivers:
  otlp: {}

# 正确：
config: |
  receivers:
    otlp: {}

错误 2：管道未定义

# 错误：pipeline 中引用了不存在的 receiver
service:
  pipelines:
    traces:
      receivers: [non-existent-receiver]

# 正确：确保 receiver 已定义
receivers:
  otlp: {}
service:
  pipelines:
    traces:
      receivers: [otlp]

错误 3：处理器配置错误

# 错误：memory_limiter 配置错误
processors:
  memory_limiter:
    limit: 75  # 错误：应该是 limit_percentage

# 正确：
processors:
  memory_limiter:
    limit_percentage: 75
    spike_limit_percentage: 15

自动注入故障排查

1. 自动注入不工作

症状

Pod 创建后，没有自动注入 instrumentation，应用容器中没有 OpenTelemetry 相关的环境变量。

诊断步骤

# 1. 检查 Pod 注解
kubectl get pod <pod-name> -o yaml | grep -A 5 annotations

# 2. 检查 Instrumentation 资源
kubectl get instrumentation -n <namespace>

# 3. 检查 Webhook 配置
kubectl get mutatingwebhookconfiguration | grep opentelemetry

# 4. 检查 Webhook 日志
kubectl logs -n opentelemetry-operator-system -l app.kubernetes.io/name=opentelemetry-operator --tail=100 | grep -i webhook

常见原因和解决方法

原因 1：Webhook 未正确配置

# 检查 MutatingWebhookConfiguration
kubectl get mutatingwebhookconfiguration opentelemetry-operator-targetallocator-mutator -o yaml

# 检查 Webhook 服务
kubectl get svc -n opentelemetry-operator-system | grep webhook

# 检查 Webhook Pod
kubectl get pods -n opentelemetry-operator-system | grep webhook

解决方法：

• 确保 Operator 已正确安装
• 检查 cert-manager 是否正常工作
• 重新安装 Operator

原因 2：Pod 注解配置错误

# 错误：注解值不正确
annotations:
  instrumentation.opentelemetry.io/inject-java: "yes"  # 应该是 "true"

# 正确：
annotations:
  instrumentation.opentelemetry.io/inject-java: "true"

原因 3：Instrumentation 资源未创建

# 检查 Instrumentation 资源
kubectl get instrumentation -A

# 如果不存在，创建 Instrumentation 资源
kubectl apply -f instrumentation.yaml

原因 4：命名空间注解配置错误

# 错误：命名空间注解指向不存在的 Instrumentation
annotations:
  instrumentation.opentelemetry.io/inject-java: "non-existent-instrumentation"

# 正确：确保 Instrumentation 资源存在
kubectl get instrumentation <name> -n <namespace>

2. 注入失败但 Pod 已创建

症状

Pod 已创建，但注入失败，Pod 中缺少 OpenTelemetry 环境变量。

诊断步骤

# 1. 检查 Pod 环境变量
kubectl exec <pod-name> -n <namespace> -- env | grep OTEL

# 2. 检查 Pod 初始化容器
kubectl get pod <pod-name> -o yaml | grep -A 10 initContainers

# 3. 检查 Webhook 日志
kubectl logs -n opentelemetry-operator-system -l app.kubernetes.io/name=opentelemetry-operator --tail=100 | grep -i <pod-name>

常见原因

原因 1：Webhook 超时

# 检查 Webhook 超时配置
kubectl get mutatingwebhookconfiguration -o yaml | grep timeoutSeconds

# 解决方法：增加超时时间或优化 Webhook 性能

原因 2：镜像拉取失败

# 检查 instrumentation 镜像配置
kubectl get instrumentation <name> -o yaml | grep image

# 检查镜像拉取错误
kubectl describe pod <pod-name> | grep -i "image\|pull"

原因 3：资源不足

# 检查节点资源
kubectl top nodes

# 检查 Pod 资源请求
kubectl get pod <pod-name> -o yaml | grep -A 10 resources

3. 注入成功但数据未发送

症状

注入成功，环境变量已设置，但应用没有发送数据到 Collector。

诊断步骤

# 1. 检查环境变量
kubectl exec <pod-name> -n <namespace> -- env | grep OTEL

# 2. 检查 Collector 端点
kubectl exec <pod-name> -n <namespace> -- env | grep OTEL_EXPORTER_OTLP_ENDPOINT

# 3. 检查网络连接
kubectl exec <pod-name> -n <namespace> -- \
  curl -v http://<collector-service>:4318/v1/traces

# 4. 检查应用日志
kubectl logs <pod-name> -n <namespace> | grep -i opentelemetry

常见原因

原因 1：Collector 端点配置错误

# 检查 Instrumentation 配置
env:
  - name: OTEL_EXPORTER_OTLP_ENDPOINT
    value: http://collector:4317  # 确保此端点可访问

原因 2：网络策略阻止连接

# 检查网络策略
kubectl get networkpolicy -n <namespace>

# 检查 Service
kubectl get svc -n <namespace> | grep collector

原因 3：Collector 未运行

# 检查 Collector Pod 状态
kubectl get pods -l app.kubernetes.io/name=opentelemetry-collector -n <namespace>

Prometheus 告警 Runbooks

OpenTelemetry Operator 提供了一些 Prometheus 告警规则来监控 Operator 的健康状态。

ReconcileErrors 告警

告警含义

OpenTelemetry Operator 在 Reconciliation 步骤中无法成功，通常是因为 OpenTelemetryCollector 配置错误。

影响

• 对已运行的部署没有影响
• 新的正确配置仍然可以正常工作
• 只有配置错误的 Collector 会受到影响

诊断方法

# 1. 检查 Operator 日志
kubectl logs -n opentelemetry-operator-system -l app.kubernetes.io/name=opentelemetry-operator --tail=100 | grep -i "error\|reconcile"

# 2. 检查 OpenTelemetryCollector 资源
kubectl get opentelemetrycollector -A

# 3. 查看有问题的 Collector 详细信息
kubectl describe opentelemetrycollector <name> -n <namespace>

# 4. 检查事件
kubectl get events -n <namespace> --sort-by='.lastTimestamp' | grep -i collector

缓解措施

1. 找出导致错误的 Collector：

   # 查看所有 Collector 状态
   kubectl get opentelemetrycollector -A -o wide
   
   # 查看有问题的 Collector 配置
   kubectl get opentelemetrycollector <name> -n <namespace> -o yaml

2. 修复配置：

   • 检查 YAML 语法
   • 验证 receivers、processors、exporters 配置
   • 确保 pipeline 配置正确

3. 验证修复：

   # 应用修复后的配置
   kubectl apply -f fixed-collector.yaml
   
   # 检查状态
   kubectl get opentelemetrycollector <name> -n <namespace>
   
   # 检查 Operator 日志确认错误已解决
   kubectl logs -n opentelemetry-operator-system -l app.kubernetes.io/name=opentelemetry-operator --tail=50

WorkqueueDepth 告警

告警含义

Operator 的工作队列深度大于 0，表示有未处理的工作项。

影响

• 如果队列深度快速恢复到 0，通常没有影响
• 如果问题持续存在，需要进一步调查
• 可能表示 Operator 处理速度跟不上资源变化速度

诊断方法

# 1. 检查 Operator 日志
kubectl logs -n opentelemetry-operator-system -l app.kubernetes.io/name=opentelemetry-operator --tail=100

# 2. 检查资源数量
kubectl get opentelemetrycollector -A | wc -l
kubectl get instrumentation -A | wc -l

# 3. 检查是否有大量资源变化
kubectl get events -A --sort-by='.lastTimestamp' | grep -i "opentelemetry\|collector\|instrumentation"

缓解措施

1. 分析日志：

   # 查看 Operator 日志，找出导致队列积压的原因
   kubectl logs -n opentelemetry-operator-system -l app.kubernetes.io/name=opentelemetry-operator --tail=200 | grep -i "error\|warning"

2. 根据日志采取行动：

   • 如果是因为配置错误，修复配置
   • 如果是因为资源过多，考虑减少资源数量
   • 如果是因为 Operator 性能问题，考虑升级 Operator 或增加资源

3. 监控队列深度：

   # 持续监控队列深度
   watch kubectl get hpa -n opentelemetry-operator-system

Target Allocator 故障排查

1. Target Allocator 无法发现 scrape targets

症状

Target Allocator 运行正常，但没有发现任何 targets，Collector 无法抓取指标。

诊断步骤

# 1. 检查 Target Allocator Pod 状态
kubectl get pods -l app.kubernetes.io/name=target-allocator -n <namespace>

# 2. 查看 Target Allocator 日志
kubectl logs -l app.kubernetes.io/name=target-allocator -n <namespace> --tail=100

# 3. 检查 Prometheus Custom Resources
kubectl get servicemonitor -A
kubectl get podmonitor -A

# 4. 检查 Collector 配置
kubectl get opentelemetrycollector <name> -o yaml | grep -A 20 "prometheus:"

常见原因和解决方法

原因 1：Prometheus Custom Resources 未创建

# 检查 ServiceMonitor/PodMonitor 是否存在
kubectl get servicemonitor -n <namespace>
kubectl get podmonitor -n <namespace>

# 如果不存在，创建相应的资源
kubectl apply -f servicemonitor.yaml

原因 2：标签选择器不匹配

# 检查 ServiceMonitor 的标签选择器
apiVersion: monitoring.coreos.com/v1
kind: ServiceMonitor
metadata:
  name: my-service-monitor
spec:
  selector:
    matchLabels:
      app: my-app  # 确保此标签与 Service 的标签匹配

解决方法：

# 检查 Service 标签
kubectl get svc -n <namespace> --show-labels

# 确保 ServiceMonitor 的标签选择器匹配

原因 3：Target Allocator 未启用 Prometheus Custom Resources 发现

确保 Target Allocator 配置正确，并且 Prometheus Operator 已安装。

2. Targets 未正确分发

症状

Target Allocator 发现了 targets，但分发不正确，某些 Collector 实例没有收到 targets。

诊断步骤

# 1. 检查 Target Allocator 日志
kubectl logs -l app.kubernetes.io/name=target-allocator -n <namespace> | grep -i "target\|allocation"

# 2. 查询 Target Allocator API
TA_SERVICE=$(kubectl get svc -l app.kubernetes.io/name=target-allocator -n <namespace> -o jsonpath='{.items[0].metadata.name}')
kubectl run -it --rm debug --image=curlimages/curl --restart=Never -- \
  curl http://$TA_SERVICE:80/jobs/<job_name>/targets

# 3. 检查 Collector Pod 数量
kubectl get pods -l app.kubernetes.io/name=opentelemetry-collector -n <namespace> | wc -l

常见原因

原因 1：Collector 实例数量变化

当 Collector 实例数量变化时，Target Allocator 需要时间重新分发 targets。

解决方法：等待几分钟，让 Target Allocator 完成重新分发。

原因 2：Target Allocator 配置错误

检查 Target Allocator 的配置，确保启用正确。

3. Collector 无法从 Target Allocator 获取 targets

症状

Target Allocator 正常运行，但 Collector 无法通过 HTTP SD API 获取 targets。

诊断步骤

# 1. 检查网络连接
kubectl exec <collector-pod-name> -n <namespace> -- \
  curl -v http://<ta-service-name>:80/jobs/<job_name>/targets?collector_id=<pod-name>

# 2. 检查 Target Allocator Service
kubectl get svc -l app.kubernetes.io/name=target-allocator -n <namespace>

# 3. 检查 Collector 配置
kubectl get configmap <collector-name>-collector -n <namespace> -o yaml | grep -A 5 http_sd_configs

# 4. 检查环境变量
kubectl exec <collector-pod-name> -n <namespace> -- env | grep POD_NAME

常见原因

原因 1：Service 未创建

# 检查 Target Allocator Service
kubectl get svc -l app.kubernetes.io/name=target-allocator -n <namespace>

# 如果不存在，检查 Target Allocator 是否启用
kubectl get opentelemetrycollector <name> -o yaml | grep -A 5 targetAllocator

原因 2：网络策略阻止连接

# 检查网络策略
kubectl get networkpolicy -n <namespace>

# 如果存在网络策略，确保允许 Collector 访问 Target Allocator

原因 3：POD_NAME 环境变量未设置

确保 Collector Pod 有 POD_NAME 环境变量，Target Allocator 使用此变量来标识 Collector Pod。

HPA 故障排查

1. HPA 不工作

症状

配置了 HPA，但 Collector 副本数没有根据负载自动调整。

诊断步骤

# 1. 检查 HPA 资源
kubectl get hpa -n <namespace>

# 2. 查看 HPA 详细信息
kubectl describe hpa <hpa-name> -n <namespace>

# 3. 检查 Metrics Server
kubectl get pods -n kube-system | grep metrics-server
kubectl top nodes

# 4. 检查 Collector 资源请求和限制
kubectl get opentelemetrycollector <name> -o yaml | grep -A 10 resources

常见原因

原因 1：Metrics Server 未安装

# 检查 Metrics Server
kubectl get pods -n kube-system | grep metrics-server

# 如果未安装，安装 Metrics Server
kubectl apply -f https://github.com/kubernetes-sigs/metrics-server/releases/latest/download/components.yaml

原因 2：资源请求和限制未配置

HPA 需要资源请求和限制才能计算使用率。

解决方法：在 OpenTelemetryCollector 资源中配置 resources。

原因 3：部署模式不支持 HPA

HPA 只支持 deployment 和 statefulset 模式。

解决方法：确保 spec.mode 设置为 deployment 或 statefulset。

2. HPA 显示 "unknown" 状态

症状

HPA 状态显示 targets 为 "unknown"，无法计算副本数。

诊断步骤

# 1. 检查 Metrics Server
kubectl get pods -n kube-system | grep metrics-server
kubectl logs -n kube-system -l k8s-app=metrics-server --tail=50

# 2. 检查 Pod 指标
kubectl top pods -n <namespace>

# 3. 检查 HPA 事件
kubectl describe hpa <hpa-name> -n <namespace> | grep -A 10 Events

常见原因

原因 1：Metrics Server 未正常工作

# 检查 Metrics Server 日志
kubectl logs -n kube-system -l k8s-app=metrics-server --tail=100

# 检查 Metrics Server API
kubectl get --raw /apis/metrics.k8s.io/v1beta1

原因 2：Pod 刚创建，还没有指标数据

等待几分钟，让 Metrics Server 收集指标数据。

调试工具和命令

常用调试命令

检查资源状态

# 检查所有 OpenTelemetry 相关资源
kubectl get opentelemetrycollector -A
kubectl get instrumentation -A
kubectl get pods -l app.kubernetes.io/name=opentelemetry-collector -A
kubectl get pods -l app.kubernetes.io/name=target-allocator -A

查看日志

# Operator 日志
kubectl logs -n opentelemetry-operator-system -l app.kubernetes.io/name=opentelemetry-operator --tail=100 -f

# Collector 日志
kubectl logs -l app.kubernetes.io/name=opentelemetry-collector -n <namespace> --tail=100 -f

# Target Allocator 日志
kubectl logs -l app.kubernetes.io/name=target-allocator -n <namespace> --tail=100 -f

查看事件

# 查看命名空间事件
kubectl get events -n <namespace> --sort-by='.lastTimestamp'

# 查看特定资源的事件
kubectl describe <resource-type> <resource-name> -n <namespace> | grep -A 20 Events

进入 Pod 调试

# 进入 Collector Pod
kubectl exec -it <collector-pod-name> -n <namespace> -- /bin/sh

# 进入应用 Pod
kubectl exec -it <app-pod-name> -n <namespace> -- /bin/sh

配置验证工具

验证 YAML 语法

# 使用 kubectl 验证
kubectl apply --dry-run=client -f collector.yaml

# 使用 yamllint 验证（需要安装）
yamllint collector.yaml

验证 Collector 配置

# 获取实际配置
kubectl get configmap <collector-name>-collector -n <namespace> -o yaml

# 使用 otelcol 验证配置（需要安装 otelcol）
# 将配置保存到文件，然后验证
otelcol validate --config config.yaml

网络调试

测试服务连接

# 从 Pod 内测试连接
kubectl exec <pod-name> -n <namespace> -- \
  curl -v http://<service-name>:<port>

# 测试 Collector OTLP 端点
kubectl exec <pod-name> -n <namespace> -- \
  curl -v http://<collector-service>:4318/v1/traces

检查 DNS 解析

# 从 Pod 内测试 DNS
kubectl exec <pod-name> -n <namespace> -- nslookup <service-name>

最佳实践

1. 定期检查 Operator 健康状态

# 创建定期检查脚本
#!/bin/bash
kubectl get pods -n opentelemetry-operator-system
kubectl get opentelemetrycollector -A
kubectl get instrumentation -A

2. 监控关键指标

• Operator Pod 状态
• Collector Pod 状态
• HPA 状态
• Target Allocator 状态

3. 设置告警规则

使用 Prometheus 告警规则监控 Operator 健康状态：

• ReconcileErrors 告警
• WorkqueueDepth 告警

4. 保留日志

定期收集和保留日志，便于问题排查：

# 收集 Operator 日志
kubectl logs -n opentelemetry-operator-system -l app.kubernetes.io/name=opentelemetry-operator > operator.log

# 收集 Collector 日志
kubectl logs -l app.kubernetes.io/name=opentelemetry-collector -A > collector.log

5. 文档化配置

为每个环境文档化配置，包括：

• Collector 配置
• Instrumentation 配置
• 资源限制
• 特殊设置

6. 测试变更

在生产环境应用变更前，先在测试环境验证：

• 配置语法
• 功能验证
• 性能测试

获取帮助

如果以上方法无法解决问题，可以：

1. 查看官方文档：

   • OpenTelemetry Operator GitHub
   • OpenTelemetry Operator 文档

2. 搜索已知问题：

   • GitHub Issues
   • Stack Overflow

3. 提交 Issue：

   • 在 GitHub 上提交详细的 Issue，包括：
     • 问题描述
     • 复现步骤
     • 日志和配置
     • 环境信息

下一步

• Operator 概述 - 了解 Operator 的基本概念
• 自动注入 - 了解自动注入功能
• 水平 Pod 自动扩缩容 - 配置 HPA
• Target Allocator - 使用 Target Allocator

参考资源

• OpenTelemetry Operator 故障排查官方文档
• 自动注入故障排查
• Prometheus 告警 Runbooks
• Target Allocator 故障排查
• OpenTelemetry Operator GitHub