企业官网建设流程全解析

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/coroot

Coroot 是一个集指标（Metrics）、日志（Logs）、追踪（Traces）、持续剖析（Profiling）与 SLO 告警于一体的开源可观测性平台。本文基于仓库内 架构文档 展开，逐层拆解其核心架构：基于 eBPF 的节点级采集代理coroot-node-agent、负责集群级数据收集的coroot-cluster-agent、以 Prometheus/ClickHouse 为核心的统一存储层，以及 OTLP、Remote Write 等数据接入协议。读完本文，你将掌握 Coroot 各组件之间的数据流与职责边界，理解其"指标缓存 + 短保留期 Prometheus"的设计取舍，以及如何规划一套覆盖指标、日志、追踪、Profile 的完整采集链路。

架构总览：四类组件各司其职

Coroot 的部署形态由四个层次构成：

这张架构图直观展示了上述组件之间的关系：coroot-node-agent与coroot-cluster-agent将各类遥测数据汇聚到 Coroot Server，Server 一方面通过磁盘缓存加速对指标存储的查询，另一方面把日志、追踪、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-endpoint=http://coroot:8080指定统一上报地址，以--wal-dir=/data启用写前日志（WAL）缓存，保证网络抖动时数据不丢失。

三种遥测协议的分流

从 node agent 配置文档 可以确认，代理对不同类型的遥测数据采用不同协议上报：

• 指标（Metrics）：Prometheus 格式或 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 配置文档）：

此外还可以在单个容器内部通过环境变量实现细粒度开关，例如COROOT_EBPF_PROFILING=disabled、COROOT_LOG_MONITORING=disabled、COROOT_EBPF_TRACES=disabled，从而跳过某些不需要监控的容器。Windows 代理使用相同的参数名，但环境变量统一以COROOT_为前缀，且仅支持平台无关的子集（eBPF L7 追踪、cgroups 等 Linux 专属能力不适用）。

Kubernetes 中的部署形态

在 Kubernetes 环境中，node agent 以DaemonSet形式部署，控制器会自动将其调度到每个节点上，从而实现"每节点一个代理"的全覆盖。若因 Pod Security 策略导致代理无法启动（Talos 等集群常见），需要在命名空间上允许特权工作负载：

kubectl label ns coroot pod-security.kubernetes.io/enforce=privileged

这是因为 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-url=http://coroot:8080连接 Coroot，--metrics-scrape-interval=15s控制抓取频率，--metrics-wal-dir=/data提供 WAL 缓冲。它还会通过--collect-kubernetes-events（默认true）收集并转发 Kubernetes 事件。

数据接入：OpenTelemetry 与 Prometheus 生态

OTLP：日志与追踪的标准入口

Coroot 支持OpenTelemetry 协议（OTLP over HTTP）接收日志与追踪数据。如果应用已使用 OpenTelemetry SDK 完成埋点，有两种接入路径：

1. 将 SDK 配置为直接上报到 Coroot 的 OTLP 端点；
2. 通过OpenTelemetry Collector作为中转，将数据路由到 Coroot。

这一设计让已具备 OTel 观测能力的存量应用可以零成本接入。从服务端看，Coroot 同时提供 gRPC 端点（默认:4317，见 服务端配置 的grpc.listenAddress）来承接标准 OTLP 流量。

Prometheus 兼容存储：任意时序数据库皆可

Coroot 使用 Prometheus 存储指标，并且兼容任何 Prometheus 兼容的时序数据库，例如：

• VictoriaMetrics
• Thanos
• Grafana 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_id="XXXX"}作为额外选择器（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 提供了一套开箱即用的参考拓扑，可以清晰看到各组件如何协作：

coroot（Server，8080 端口） ├── 依赖 prometheus:9090、clickhouse:9000（健康检查通过后才启动） ├── 接收 node-agent 推送（--collector-endpoint=http://coroot:8080） └── 接收 cluster-agent 推送（--coroot-url=http://coroot:8080） node-agent（privileged + 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