Coroot 架构深度解析Node Agent、Cluster 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/corootCoroot 是一个集指标Metrics、日志Logs、追踪Traces、持续剖析Profiling与 SLO 告警于一体的开源可观测性平台。本文基于仓库内 架构文档 展开逐层拆解其核心架构基于 eBPF 的节点级采集代理coroot-node-agent、负责集群级数据收集的coroot-cluster-agent、以 Prometheus/ClickHouse 为核心的统一存储层以及 OTLP、Remote Write 等数据接入协议。读完本文你将掌握 Coroot 各组件之间的数据流与职责边界理解其指标缓存 短保留期 Prometheus的设计取舍以及如何规划一套覆盖指标、日志、追踪、Profile 的完整采集链路。架构总览四类组件各司其职Coroot 的部署形态由四个层次构成组件职责数据方向Coroot Server汇总、缓存、审计分析、UI/API 与告警接收各 agent 推送的数据缓存指标coroot-node-agent逐节点采集容器与主机遥测eBPF指标经 Prometheus 格式 / Remote Write日志与追踪经 OTLPProfile 经自定义 HTTP 协议coroot-cluster-agent集群级数据库、Kubernetes 状态与事件、应用级 Profile、AWS 云资源经 Prometheus Remote Write 上报Prometheus / ClickHouse时序与日志类数据的持久化存储作为 Coroot 的数据源与后端这张架构图直观展示了上述组件之间的关系coroot-node-agent与coroot-cluster-agent将各类遥测数据汇聚到 Coroot ServerServer 一方面通过磁盘缓存加速对指标存储的查询另一方面把日志、追踪、Profile以及可选的指标写入 ClickHouse。Coroot-node-agent基于 eBPF 的节点级可观测性代理coroot-node-agent是一个开源、由 eBPF 驱动的可观测性代理负责收集节点上所有容器的指标、日志、追踪与 Profile。它的工作边界是单节点全覆盖因此文档明确指出要保证覆盖完整性集群中的每一个节点都必须安装它。支持 Pull / Push 双模式的指标采集代理在指标采集上同时支持两种模式Pull 模式以 Prometheus 格式暴露/metrics端点由外部抓取Push 模式通过 Prometheus Remote Write 协议直接将指标发送给 Coroot。默认监听地址为0.0.0.0:80对应--listen/LISTEN参数可供 Prometheus 等抓取器拉取。在 docker-compose 参考部署 中可以看到代理的实际启动形态以特权模式运行并挂载宿主的/sys/kernel/tracing、/sys/kernel/debug、/sys/fs/cgroup通过--collector-endpointhttp://coroot:8080指定统一上报地址以--wal-dir/data启用写前日志WAL缓存保证网络抖动时数据不丢失。三种遥测协议的分流从 node agent 配置文档 可以确认代理对不同类型的遥测数据采用不同协议上报指标MetricsPrometheus 格式或 Prometheus Remote Write日志Logs自动发现容器日志经 OTLP/HTTP 发送追踪Traces基于 eBPF 的网络与应用层追踪经 OTLP/HTTP 发送Profile使用 Pyroscope eBPF 剖析器收集 CPU 火焰图数据经自定义 HTTP 协议发送。也就是说日志与追踪走 OpenTelemetry 标准协议Profile 走专属通道。在 服务端路由实现 中可以看到与之对应的接收端点/v1/metrics、/v1/traces、/v1/logs、/v1/profiles、/v1/config各协议数据在 Coroot Server 侧由 collector 统一接收落库。常用配置速查代理支持命令行参数与环境变量两种配置方式以下是影响采集行为的关键参数完整清单见 node agent 配置文档参数环境变量默认值说明--collector-endpointCOLLECTOR_ENDPOINT–统一遥测上报基址Coroot 地址--api-keyAPI_KEY–Coroot API Key--disable-l7-tracingDISABLE_L7_TRACINGfalse关闭应用层L7追踪--traces-samplingTRACES_SAMPLING1.0追踪采样率0.0 ~ 1.0--disable-gpu-monitoringDISABLE_GPU_MONITORINGfalse关闭 GPUNVML监控--container-allowlist/--container-denylistCONTAINER_ALLOWLIST/CONTAINER_DENYLIST–容器监控白名单 / 黑名单正则--track-public-networkTRACK_PUBLIC_NETWORK0.0.0.0/0需要追踪的公网网段--max-spool-sizeMAX_SPOOL_SIZE500MB磁盘 Spool 上限--wal-dirWAL_DIR/tmp/coroot-node-agentWAL 存储目录此外还可以在单个容器内部通过环境变量实现细粒度开关例如COROOT_EBPF_PROFILINGdisabled、COROOT_LOG_MONITORINGdisabled、COROOT_EBPF_TRACESdisabled从而跳过某些不需要监控的容器。Windows 代理使用相同的参数名但环境变量统一以COROOT_为前缀且仅支持平台无关的子集eBPF L7 追踪、cgroups 等 Linux 专属能力不适用。Kubernetes 中的部署形态在 Kubernetes 环境中node agent 以DaemonSet形式部署控制器会自动将其调度到每个节点上从而实现每节点一个代理的全覆盖。若因 Pod Security 策略导致代理无法启动Talos 等集群常见需要在命名空间上允许特权工作负载kubectl label ns coroot pod-security.kubernetes.io/enforceprivileged这是因为 eBPF 监控、宿主文件系统访问与容器检查都需要特权能力详见 Kubernetes 安装文档 的 Troubleshooting 章节。Coroot-cluster-agent集群级遥测收集器coroot-cluster-agent是专门负责集群范围遥测数据收集的组件它与逐节点工作的 node agent 形成互补。文档明确了它的三项核心职责。1. 数据库指标发现与采集通过 Coroot 的 Service Map服务地图自动发现集群中的数据库实例并使用 Coroot 下发的凭据连接Postgres、MySQL、Redis、Memcached、MongoDB采集数据库专属指标后经 Prometheus Remote Write 上报给 Coroot。该代理还可通过--config-file读取静态 YAML 配置支持${VAR}环境变量展开补充在 Coroot UI 之外配置的数据库目标例如databases: - type: postgres # postgres, mysql, redis, memcached 或 mongodb rds: my-db # 由 AWS 集成发现到的 RDS 实例 credentials: {username: coroot, password: ${PG_PASSWORD}} params: {sslmode: require} - type: redis elasticache: my-cache # ElastiCache 集群每个节点都会被监控 - type: mysql host: mysql.example.internal port: 3306 credentials: {username: coroot, password: ${MYSQL_PASSWORD}}其中 AWS 配置项region、accessKeyId、secretAccessKey、rdsTagFilters、elasticacheTagFilters可覆盖 UI 中设置的 AWS 集成rdsTagFilters/elasticacheTagFilters用于按资源标签Tag过滤要纳管的 RDS/ElastiCache 实例完整示例见 cluster agent 配置文档。2. 应用级 Profile 采集除了 node agent 内置的 eBPF 持续剖析器Coroot 还支持应用级剖析cluster agent 可以发现带有coroot.com/profile-scrape与coroot.com/profile-port注解Annotation的 Go 应用从其实例上抓取 CPU 与内存 Profile。3. AWS 云资源集成代理可对接 AWS自动发现RDS 与 ElastiCache集群并采集其遥测数据将数据库的采集范围从集群内部扩展到托管云服务。在 docker-compose 参考部署 中cluster agent 以--coroot-urlhttp://coroot:8080连接 Coroot--metrics-scrape-interval15s控制抓取频率--metrics-wal-dir/data提供 WAL 缓冲。它还会通过--collect-kubernetes-events默认true收集并转发 Kubernetes 事件。数据接入OpenTelemetry 与 Prometheus 生态OTLP日志与追踪的标准入口Coroot 支持OpenTelemetry 协议OTLP over HTTP接收日志与追踪数据。如果应用已使用 OpenTelemetry SDK 完成埋点有两种接入路径将 SDK 配置为直接上报到 Coroot 的 OTLP 端点通过OpenTelemetry Collector作为中转将数据路由到 Coroot。这一设计让已具备 OTel 观测能力的存量应用可以零成本接入。从服务端看Coroot 同时提供 gRPC 端点默认:4317见 服务端配置 的grpc.listenAddress来承接标准 OTLP 流量。Prometheus 兼容存储任意时序数据库皆可Coroot 使用 Prometheus 存储指标并且兼容任何 Prometheus 兼容的时序数据库例如VictoriaMetricsThanosGrafana Mimir在 docker-compose 参考部署 中Prometheus 以--web.enable-remote-write-receiver开启 Remote Write 接收端使 node agent 与 cluster agent 可以直接推送指标而集群版 VictoriaMetrics 场景下可以将 ingestion 指向vminsert、查询指向vmselect见 Prometheus 集成文档。多租户模式Coroot 支持多租户Multi-tenancy模式让单个 Prometheus 同时存储多个项目或集群的指标。此时所有 agent 都通过 Remote Write 推送到 Coroot由 Coroot 自动为每条指标附加coroot_project_id标签并在查询时使用{coroot_project_idXXXX}作为额外选择器Selector隔离项目数据。对应的租户隔离在 ClickHouse 侧则体现为每项目独立数据库详见 ClickHouse 集成文档。指标缓存把 Prometheus 当作缓存更新源这是 Coroot 架构中非常关键的一个设计Coroot 维护自己的磁盘指标缓存持续从 Prometheus 拉取指标。Prometheus任意兼容存储保留期可短至几小时 │ 持续拉取 ▼ Coroot 磁盘指标缓存--cache-ttl 控制保留 │ 本地快速查询 ▼ 审计Audit与 UI 展示正因为 Coroot 把时序数据库视为用于更新自身缓存的来源用户可以放心地把 Prometheus 的保留期Retention配置得很短——例如几个小时——以节省存储成本而无需担心历史数据查询受影响。缓存保留期可通过--cache-ttl参数或CACHE_TTL环境变量调整config 默认值为 30 天可依据磁盘规划调整。相应地服务端配置结构 中Metrics、Traces、Logs、Profiles均提供独立的 TTL 配置默认各为 7 天。ClickHouse统一的可观测性数据底座Coroot 使用 ClickHouse 存储日志、追踪、Profile以及可选的指标。文档强调了两点核心收益10 倍以上压缩比得益于 ClickHouse 高效的数据压缩实现列式存储与时序数据的天然契合列式布局对时序指标极其友好压缩与查询性能俱佳。当同时配置了 Prometheus 与 ClickHouse 时Coroot 会优先使用 ClickHouse 存储指标从而将四类遥测数据全部收敛到同一套存储系统对应--global-prometheus-use-clickhouse开关或 UI 中的 Use ClickHouse for metrics storage 选项。ClickHouse 化指标存储的优势包括统一存储、更好的压缩、依托分布式架构的扩展性以及合并存储系统带来的成本效率。集群自动发现与多租户从 ClickHouse 客户端源码 可以看到Coroot 在建立连接后会执行集群发现逻辑通过EXISTS system.zookeeper判断是否运行在 ZooKeeper 之上通过SELECT count(DISTINCT cluster) FROM system.clusters检测集群数量并启用分布式表useDistributed若检测到cloud_mode_engine设置则判定为云端托管环境。对应 ClickHouse 集成文档 的说明Coroot 自动选择建表目标的策略是无集群时在单实例上建表只有一个集群时使用该集群存在多个集群时优先选择名为coroot的集群其次回退到default。多租户模式下Coroot 会为每个项目自动创建独立的数据库如coroot_xxxxx由各项目的 agent 数据分别落库实现项目级隔离。磁盘治理Space Manager 与 S3为防止日志、追踪等海量数据写满磁盘Coroot 内置了Space Manager空间管理器当磁盘使用率达到阈值时自动删除各遥测表中最旧的数据分区分区通常按天切分并且始终保留至少min_partitions个分区——即便 TTL 设置为 7 天在磁盘紧张时可能只保留 6 天数据优先保证系统持续运行。相关默认值启用、阈值 70%、最小分区 1定义在 服务端配置同时支持clickhouse_space_manager配置节、环境变量与命令行参数三种调整方式。当配置了 S3 存储时tiered分层模式或s3only纯 S3 模式数据会按moveFactor阈值自动从本地磁盘迁移到 S3此时 Space Manager 自动关闭因为磁盘压力改由数据迁移而非删除来缓解。部署形态与端到端数据流仓库中的 docker-compose.yaml 提供了一套开箱即用的参考拓扑可以清晰看到各组件如何协作corootServer8080 端口 ├── 依赖 prometheus:9090、clickhouse:9000健康检查通过后才启动 ├── 接收 node-agent 推送--collector-endpointhttp://coroot:8080 └── 接收 cluster-agent 推送--coroot-urlhttp://coroot:8080 node-agentprivileged host PID └── eBPF 采集 → Remote Write / OTLP / 自定义 HTTP → coroot cluster-agent └── 数据库 / K8s 事件 / Profile / AWS → Remote Write → coroot服务端还提供了/health健康检查端点以及--bootstrap-prometheus-url、--bootstrap-clickhouse-address等引导参数让部署在首次启动时即可自动对接存储后端见 主程序入口 与 bootstrap 逻辑。在 Kubernetes 中社区版与企业版均可通过 Helm Coroot Operator 安装Operator 负责自动升级各组件镜像除非你在 Coroot Custom Resource 中固定了镜像版本安装步骤见 Kubernetes 安装文档。小结Coroot 的架构本质上是eBPF 全量采集 标准协议接入 缓存加速 统一列式存储的组合node agent 负责广度每节点一个覆盖全部容器的四类遥测cluster agent 负责纵深数据库、Kubernetes 事件、应用级 Profile 与云资源Prometheus/兼容存储 磁盘缓存用短保留期换存储成本靠本地缓存保证查询体验ClickHouse 负责统一日志、追踪、Profile可选含指标一体化存储配合 Space Manager 与 S3 实现磁盘自愈与成本分层。理解这条从采集、接入到存储的链路是规划 Coroot 生产部署、预估存储开销以及排查数据缺失问题的第一步。各 agent 的完整参数清单、ClickHouse 集群化与 S3 配置、多租户细节可进一步阅读仓库中的 node agent 配置、cluster agent 配置、Prometheus 集成 与 ClickHouse 集成 文档。【免费下载链接】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），仅供参考