Coroot 可观测平台实战指南：从部署权限到 eBPF 采集、日志调优与多集群聚合的完整排查手册-开发者社区

Coroot 可观测平台实战指南：从部署权限到 eBPF 采集、日志调优与多集群聚合的完整排查手册

【免费下载链接】corootCoroot is an open-source observability and APM tool with AI-powered Root Cause Analysis. It combines metrics, logs, traces, continuous profiling, and SLO-based alerting with predefined dashboards and inspections.项目地址: https://gitcode.com/GitHub_Trending/co/coroot

Coroot 是一个基于 eBPF 的零侵入可观测平台，靠 eBPF 探针自动完成服务发现、性能诊断与 SLO 告警，无需在应用里埋代码。这篇指南按"部署 → 采集 → 分析 → 调优 → 扩展"的先后顺序，带你处理新手最常遇到的五类现象：页面打不开、eBPF 程序挂载失败、服务地图空白、查询变慢、以及多集群数据看不全。每个小节都按"你看到什么现象 → 背后是什么原因 → 用什么命令或配置解决"的顺序展开。

一、Coroot 部署不起来的权限与内核排查

本节解决 Coroot 容器反复重启或探针无输出的启动问题。

1.1 现象：容器启动即退出，先查内核版本

Coroot 重度依赖 eBPF，官方系统要求明确最低支持 Linux 内核 5.1，并依赖 CO-RE 特性。如果你发现主容器能起来但 node-agent 始终不出数据，先在宿主机上确认内核：

uname -r # 输出须 ≥ 5.1，例如 5.15.0-91-generic

低于 5.1 的内核不要尝试降级适配，按 Ubuntu 安装文档或 RHEL 安装文档升级内核。

1.2 原因：node-agent 缺少特权与 tracefs 挂载

eBPF 探针由 coroot-node-agent 采集，它必须运行在特权模式下，并挂载宿主机的 tracefs。查看 docker-compose 部署文件中 node-agent 段落：privileged: true、pid: host两个配置项和/sys/kernel/tracing、/sys/kernel/debug的卷挂载缺一不可。自己写编排文件时漏掉任何一项，典型现象就是 agent 日志里反复报 eBPF 程序 attach 失败。

1.3 方案：对齐官方编排文件再启动

💡 最稳妥的做法是直接复用官方 deploy/docker-compose.yaml 里的 node-agent 段，逐项核对特权、PID 命名空间、挂载卷三处，改完执行docker compose up -d后等 1 分钟再刷新页面。另外注意 Docker-in-Docker 环境（如 MiniKube）因 eBPF 限制不被支持，WSL1 同样不在支持列表内。

二、eBPF 程序挂载失败的排查命令

本节解决 node-agent 日志中Failed to attach eBPF program一类报错。

2.1 现象：agent 日志反复出现挂载失败

典型报错是Failed to attach eBPF program，且服务地图长期无新应用。原因通常有两类：宿主机缺少内核头文件导致编译失败，或者容器内 eBPF 工具链与宿主机内核版本不匹配。

2.2 原因：内核头文件缺失

Debian/Ubuntu 系统执行apt-get install -y linux-headers-$(uname -r)，RHEL/CentOS 系统执行yum install -y kernel-devel-$(uname -r)。⚠️ 装完头文件后必须重启，否则运行中的内核与新装的头文件仍然对不上。

2.3 方案：用官方镜像绕开工具链问题

Coroot 官方镜像已内置与目标内核匹配的预编译 eBPF 程序，采集端逻辑见 collector 模块。自建镜像时务必基于官方基础镜像，不要在 alpine 等精简镜像里自行编译 bcc/bpf 工具链——这是踩坑率最高的一处。

三、服务地图为空时的服务发现排查

本节解决应用列表、服务地图页面长时间空白的问题。

3.1 现象：地图空白但容器日志正常

先区分两种空白：整个项目没有任何应用（采集链路断了，回到第二节），还是只有个别自研服务不在图上（发现规则问题）。后者是这一节要解决的。

3.2 原因：eBPF 只认 Pod 级流量，自定义服务需要规则

Coroot 对 K8s Pod、Docker 容器、systemd 服务都支持自动发现，但非标准命名的服务有时会被归并或漏掉。可以在项目配置里用customApplications显式声明，配置结构见 config/project.go，同时在 UI 的 Custom Applications 页面维护端口与匹配规则。

3.3 方案：声明自定义应用后验证端口

给遗漏的服务补一条自定义应用规则并写上监听端口，保存后刷新服务地图。若仍不出现，回到 node-agent 日志确认该容器的 cgroup 是否被采集端识别，必要时检查网络策略是否阻断了 agent 与 Coroot 主服务 8080 端口的通信。

四、CPU 火焰图的生成与解读方法

本节解决"指标显示 CPU 高，但不知道是哪个函数在烧 CPU"的问题。

4.1 现象：CPU 指标飙高但无法定位

Inspections 的 CPU 检查项会先给出延迟、Throttled Time、用量等概览（检查逻辑见 auditor/cpu.go）。但当你想进一步看到具体函数栈时，需要打开应用详情页的 Profiling 功能，它基于 eBPF 持续剖析，无需在代码里加任何插桩，原理见 eBPF 剖析文档。

4.2 原因与方案：按"宽-高-颜色"三步读火焰图

横向宽度：函数在本次采样中的时间占比，越宽说明烧的 CPU 越多，优先看最宽的顶层块
纵向深度：调用栈层级，从底向上是调用链，点击某块可以展开完整路径
颜色区分：不同运行态（用户态/内核态）着色不同，内核态占比高时要重点检查系统调用

💡 实操建议：先在 CPU 检查项里确认"是延迟高还是 Throttled Time 高"，再进火焰图验证——Throttled 高是资源限额问题，改 requests/limits 比优化代码更快。

五、ClickHouse 日志查询慢的调优项

本节解决日志、追踪页面响应越来越慢，以及磁盘告警的问题。

5.1 现象：查询耗时随数据量增长

日志、Traces、Profiles 都存在 ClickHouse 中。查询变慢通常不是 Coroot 的问题，而是 ClickHouse 自身内存与保留策略没按数据量调整。

5.2 原因：单查询内存上限过低

在 ClickHouse 用户配置中适当调大单查询内存上限，避免大时间范围查询被内存限制截断：

<!-- ClickHouse profiles 配置示例 --> <profiles><default> <max_memory_usage>8GB</max_memory_usage> <!-- 按实例内存调整 --> </default></profiles>

完整说明见 ClickHouse 配置文档。

5.3 方案：用 Space Manager 控制磁盘水位

Coroot 内置 Space Manager 会在磁盘使用率超过阈值（默认 70%）时删除最老的日分区，实现见 space_manager.go。调优项有三个：clickhouse_space_manager.usage_threshold_percent（清理水位）、min_partitions（最少保留分区数）、开关clickhouse_space_manager.disabled。⚠️ 注意它只删遥测数据，且磁盘紧张时实际保留期会短于你设置的 TTL。

六、多集群聚合与 OpenTelemetry 追踪集成

本节解决"多个集群/区域的数据无法在一个视图里看"的问题。

6.1 现象：各区域 Coroot 各自独立

如果同一个应用跑在多个 K8s 集群，逐个登录各集群的 Coroot 看数据非常低效。Coroot 的解法是多集群项目：创建一个聚合项目，把各成员项目选进去即可。

6.2 方案：memberProjects 聚合配置

在configuration.yaml中给聚合项目声明memberProjects列表即可，成员项目必须先存在：

projects: - name: prod-global # 聚合视图项目 memberProjects: - prod-eu # 成员：欧洲集群 - prod-us # 成员：美东集群

要点来自多集群文档：聚合项目本身不直接接收遥测，Prometheus/ClickHouse 集成配置都留在成员项目上，且不支持嵌套聚合。

6.3 进阶：接入 OpenTelemetry 应用级追踪

eBPF 采集的是网络与系统层数据，而调用链的完整性依赖应用侧埋点。Java、Go、Python 应用可以按 Java 追踪文档与 Python 追踪文档接入 OpenTelemetry SDK 并导出 OTLP 数据到 Coroot，这样服务地图上的每条调用边都带有精确的 span 属性，分布式追踪才完整。

写在最后

排查能力跑通之后，还有三个值得花时间的方向：AI 辅助诊断（让模型基于指标与日志给出根因报告，见 AI 文档）、成本分析（按应用维度看云资源消耗，见成本文档）、自定义仪表盘（沉淀业务专属视图，见仪表盘文档）。遇到问题时，先到对应模块的文档目录里检索报错原文；如果要在社区求助，附上 Coroot 主容器与两个 agent 的日志包，能明显加快他人定位的速度。

创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考