Coroot实战排障：从症状到根治的5个核心问题解决指南

一、日志采集异常：数据管道断裂修复

问题定位

当Coroot UI的日志页面无数据展示或出现"No logs available"提示时，可能存在日志采集链路中断。典型表现为：

• 应用日志在容器内可查但Coroot未显示
• OpenTelemetry Agent状态正常但无数据流入
• ClickHouse日志出现"Insertion failed"错误

根源分析

日志采集依赖OTLP协议传输、Collector处理和ClickHouse存储的完整链路。常见故障点包括：

1. 数据格式错误（非Protobuf格式）
2. Collector批处理溢出（默认限制1000条/批）
3. ClickHouse连接超时或表结构不匹配

解决方案

方案A：命令行诊断与修复

# 1. 检查Collector日志
docker logs coroot-collector | grep "LogsBatch"

# 预期输出：应包含"save()"成功日志，无"klog.Errorln"错误

# 2. 验证ClickHouse连接
docker exec -it coroot-clickhouse clickhouse-client -q "SELECT count() FROM otel_logs"

# 预期输出：非零数值，表明有日志数据存储

方案B：配置文件调整

修改collector/config.go调整批处理参数：

// 增大批处理容量和超时时间
func NewLogsBatch(limit int, timeout time.Duration, exec func(query ch.Query) error) *LogsBatch {
    return &LogsBatch{
        limit: 5000,  // 从1000调整为5000
        // ...其他配置
    }
}

方案C：UI状态检查

1. 访问Coroot的Integrations页面
2. 查看OpenTelemetry集成状态
3. 点击"Test Connection"验证数据接收

预防措施

• 设置日志采集监控告警：rate(otel_logs_errors_total[5m]) > 0
• 定期执行日志完整性检查脚本：

#!/bin/bash
# 检查最近5分钟是否有日志写入
count=$(docker exec -it coroot-clickhouse clickhouse-client -q \
  "SELECT count() FROM otel_logs WHERE Timestamp > now() - INTERVAL 5 MINUTE")
if [ $count -eq 0 ]; then
  echo "日志采集异常" | mail -s "Coroot Alert" [e-mail]
fi

问题预警指标

• Collector指标：coroot_collector_logs_dropped_total > 0
• ClickHouse指标：clickhouse_http_requests_total{status="500"} > 0
• 网络指标：9091端口（OTLP）流量为0

二、eBPF程序加载失败：内核兼容性修复

问题定位

节点代理启动失败，日志中出现"Failed to attach eBPF program: invalid argument"错误。常见于：

• 新部署的节点
• 内核版本升级后
• 容器重启后

根源分析

eBPF程序依赖特定内核特性，主要兼容性问题包括：

1. 内核版本低于5.4（缺少必要的eBPF helper函数）
2. 缺少内核头文件（无法编译BPF程序）
3. 容器权限不足（未启用CAP_BPF能力）

解决方案

方案A：环境检查与修复

# 1. 验证内核版本
uname -r | awk -F. '{if ($1*1000 + $2 < 5004) print "内核版本过低"; else print "内核版本兼容"}'

# 2. 安装内核头文件
# Debian/Ubuntu
apt-get install -y linux-headers-$(uname -r)
# RHEL/CentOS
yum install -y kernel-devel-$(uname -r)

方案B：容器配置调整

修改deploy/docker-compose.yaml：

services:
  coroot-node-agent:
    cap_add:
      - CAP_BPF          # 必需：允许加载eBPF程序
      - CAP_PERFMON      # 必需：性能监控能力
      - CAP_SYS_ADMIN    # 可选：系统信息采集
    volumes:
      - /sys/kernel/debug:/sys/kernel/debug:ro  # eBPF调试文件系统
      - /lib/modules:/lib/modules:ro            # 内核模块访问

方案C：预编译eBPF程序

对于内核版本不兼容场景，使用预编译的eBPF程序：

# 下载对应内核版本的预编译模块
wget https://coroot-releases.s3.amazonaws.com/ebpf/5.4.0/bpf-progs.o -O /var/lib/coroot/bpf-progs.o

# 修改节点代理启动参数
-e "BPF_PROGS_PATH=/var/lib/coroot/bpf-progs.o"

预防措施

• 在新节点加入前执行兼容性检查脚本：

#!/bin/bash
# 检查eBPF兼容性
if ! grep -q BPF /proc/modules; then
  echo "eBPF模块未加载"
  exit 1
fi

• 使用官方提供的内核兼容性矩阵验证环境

问题预警指标

• 节点代理状态：coroot_node_agent_bpf_attachments_failed_total > 0
• 内核日志：dmesg | grep -i bpf 出现"denied"或"invalid"字样
• 容器状态：node-agent容器重启次数 > 3次/小时

三、ClickHouse查询超时：性能优化指南

问题定位

在Coroot UI执行日志或指标查询时，页面长时间加载后显示"Query timeout"错误。特征包括：

• 简单查询（如最近1小时数据）正常
• 复杂聚合查询（如7天趋势分析）失败
• ClickHouse容器CPU使用率持续>80%

根源分析

ClickHouse查询性能问题通常源于：

1. 内存配置不足（默认max_memory_usage=4GB）
2. 分区策略不合理（按天分区导致大表扫描）
3. 缺少合适的索引（特别是时间范围查询）

解决方案

方案A：内存配置优化

修改clickhouse/clickhouse.go调整内存参数：

// 增加内存分配
func DefaultClickHouseConfig() *Config {
    return &Config{
        MaxMemoryUsage: 8 * 1024 * 1024 * 1024, // 8GB
        MaxThreads:     4,                       // 根据CPU核心数调整
        // ...其他配置
    }
}

方案B：分区策略调整

修改clickhouse/space_manager.go实现按小时分区：

// 按小时分区示例
func getPartitionKey(t time.Time) string {
    return t.Format("2006010215") // 格式：年月日小时
}

方案C：UI查询优化

1. 在Coroot查询界面使用时间范围限制（默认24小时）
2. 启用采样模式（点击查询设置中的"Sampling"）
3. 减少同时展示的指标数量（单面板不超过5个指标）

预防措施

• 设置定期优化任务：

-- 每周日凌晨执行表优化
OPTIMIZE TABLE otel_logs FINAL;

• 监控慢查询日志：

tail -f /var/lib/clickhouse/logs/query_log.tsv | grep -i "QueryDuration" | awk '$4 > 10 {print}'

问题预警指标

• 查询性能：clickhouse_queries_total{type="Select"} 平均耗时>1s
• 内存使用：clickhouse_memory_usage 持续>90%
• 磁盘I/O：iostat -x 1 中 %util > 90%

四、分布式追踪断裂：OpenTelemetry集成修复

问题定位

服务地图中显示"Broken trace"或追踪详情仅包含部分服务。典型表现：

• 上下游服务间无连接线条
• trace ID在服务间不连续
• "Trace details"页面显示"Incomplete trace"

根源分析

分布式追踪依赖跨服务的上下文传递，常见问题包括：

1. 未正确传递traceparent HTTP头
2. 服务未集成OpenTelemetry SDK
3. 采样率配置过低导致部分trace被丢弃

解决方案

方案A：应用集成验证

以Java应用为例，检查依赖配置：

<!-- pom.xml -->
<dependency>
  <groupId>io.opentelemetry</groupId>
  <artifactId>opentelemetry-exporter-otlp</artifactId>
  <version>1.32.0</version>
</dependency>

方案B：上下文传递修复

确保所有HTTP客户端正确传递追踪上下文：

// Go语言示例：使用otelhttp中间件
client := &http.Client{
    Transport: otelhttp.NewTransport(http.DefaultTransport),
}
resp, err := client.Get("http://downstream-service/api")

方案C：采样率调整

修改OpenTelemetry Collector配置：

processors:
  batch:
  probabilistic_sampler:
    hash_seed: 22
    sampling_percentage: 100  # 开发环境100%采样

预防措施

• 实施追踪完整性测试：

# 发送测试请求并验证trace完整性
curl -H "X-Test-Trace: true" https://api.example.com/test

• 监控追踪指标：

# 追踪断裂率 = 不完整trace数 / 总trace数
sum(otel_traces_span_count{status_code="ERROR"}) / sum(otel_traces_span_count)

问题预警指标

• 追踪指标：otel_traces_spans_dropped_total > 0
• 上下文指标：otel_trace_context_propagation_errors_total > 0
• 服务依赖：服务地图中出现孤立节点

五、告警风暴：智能抑制策略实现

问题定位

短时间内收到大量重复告警，如"High CPU usage"在5分钟内触发20次。主要影响：

• 告警通道被淹没
• 重要告警被忽略
• 值班人员疲劳

根源分析

告警风暴通常源于：

1. 缺乏告警合并机制
2. SLO阈值设置不合理
3. 未配置告警依赖关系

解决方案

方案A：代码级告警抑制

修改notifications/notifications.go实现告警合并：

// 添加5分钟相同告警抑制逻辑
func shouldSendAlert(lastAlert *db.AlertNotification, newAlert *db.AlertNotification) bool {
    if lastAlert == nil {
        return true
    }
    // 相同应用、相同规则、相同严重级别
    if lastAlert.ApplicationId == newAlert.ApplicationId &&
       lastAlert.Details.RuleName == newAlert.Details.RuleName &&
       lastAlert.Severity == newAlert.Severity &&
       time.Since(lastAlert.CreatedAt) < 5*time.Minute {
        return false // 抑制发送
    }
    return true
}

方案B：SLO阈值优化

在UI中调整SLO配置：

1. 访问"Inspections"页面
2. 选择目标应用的SLO规则
3. 调整"Alert threshold"从99%提高到99.9%
4. 增加"Grace period"至5分钟

方案C：告警依赖配置

通过配置文件设置告警依赖：

# config/alerting_rules.yaml
rules:
  - name: high_cpu_usage
    description: CPU使用率持续5分钟超过80%
    severity: warning
    depends_on:
      - node_unavailable  # 节点不可用时不发送CPU告警

预防措施

• 实施告警风暴演练：

# 模拟CPU告警风暴测试抑制效果
for i in {1..100}; do curl -X POST http://coroot-api/alerts/simulate -d '{"rule":"high_cpu","app":"test"}'; done

• 配置告警聚合视图：

-- ClickHouse查询最近1小时告警分布
SELECT severity, count() FROM alerts WHERE time > now() - 3600 GROUP BY severity

问题预警指标

• 告警频率：coroot_alerts_total 5分钟内增长>10次
• 告警类型：单一规则触发占比>80%
• 抑制率：coroot_alerts_suppressed_total / coroot_alerts_total < 0.1

常见误区对比

错误做法	正确操作	影响
使用默认内存配置运行ClickHouse	根据服务器规格调整MaxMemoryUsage	默认4GB可能导致大查询OOM
对所有服务使用相同的SLO阈值	按服务重要性差异化配置SLO	非核心服务告警淹没关键业务告警
未限制eBPF采集频率	根据应用负载调整采样间隔	高频率采集可能影响系统性能
直接在生产环境修改配置	通过配置中心或CI/CD流程更新	直接修改可能导致服务中断
忽略内核版本要求	部署前执行兼容性检查	eBPF功能不可用，监控数据缺失

问题自愈检查清单

• [ ] 所有节点内核版本≥5.4
• [ ] ClickHouse内存配置≥物理内存50%
• [ ] 容器已添加CAP_BPF和CAP_PERFMON权限
• [ ] OpenTelemetry SDK版本与Collector兼容
• [ ] 告警规则已配置5分钟合并窗口
• [ ] 日志批处理大小已根据流量调整
• [ ] 定期执行ClickHouse表优化
• [ ] 追踪上下文在所有服务间正确传递
• [ ] 节点代理日志无eBPF相关错误
• [ ] 关键查询响应时间<2秒

问题反馈模板

当遇到无法解决的问题时，请提交包含以下信息的issue：

1. 问题描述：

   • 症状表现
   • 复现步骤
   • 预期行为

2. 环境信息：

   • Coroot版本：docker exec coroot-version
   • 内核版本：uname -r
   • 部署方式：Docker/K8s

3. 诊断数据：

   • 相关日志：corootctl collect-logs
   • 指标截图：问题发生时的关键指标
   • 配置文件：已修改的配置片段

4. 已尝试的解决方案：

   • 列出已执行的排查步骤
   • 相关文档参考链接