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/corootCoroot 是一个基于 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 配置示例 -- profilesdefault max_memory_usage8GB/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 的日志包能明显加快他人定位的速度。【免费下载链接】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创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考