Coroot Node Agent 配置完全指南：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-node-agent 是 Coroot 可观测性平台中负责节点侧数据采集的代理组件：它以 Prometheus 与 OpenTelemetry 兼容的方式，从宿主机上每一个容器以及节点自身收集指标、日志、链路追踪与性能剖析数据，并统一推送到 Coroot 服务端。本文以 docs/docs/configuration/coroot-node-agent.md 为主体，完整梳理该 Agent 的全部命令行参数、环境变量与容器级开关，并结合仓库内的部署清单与配套文档，给出可直接落地的安装与调优方案。
一、Agent 在 Coroot 架构中的定位
在 Coroot 的架构文档中，coroot-node-agent被定义为「由 eBPF 驱动的开源可观测性 Agent」，负责采集节点上所有容器的 metrics、logs、traces 与 profiles。它通常以 Kubernetes DaemonSet 形式在每个节点部署一份（见 kubernetes 安装文档），或在 Docker、Docker Swarm、裸机 Linux、Windows 主机上独立运行。因为 eBPF 监控、宿主机文件系统访问与容器检视都需要特权，Kubernetes 中若因 Pod Security 标准导致 Agent 无法启动，需要放行特权工作负载：
kubectl label ns coroot pod-security.kubernetes.io/enforce=privileged从 deploy/docker-compose.yaml 中可以看到生产可用的最小部署形态——node-agent服务以 privileged + host PID 运行，挂载内核追踪与调试目录，并显式传入三个关键参数：
node-agent: restart: always image: ghcr.io/coroot/coroot-node-agent pull_policy: always privileged: true pid: "host" volumes: - /sys/kernel/tracing:/sys/kernel/tracing - /sys/kernel/debug:/sys/kernel/debug - /sys/fs/cgroup:/host/sys/fs/cgroup - node_agent_data:/data command: - '--collector-endpoint=http://coroot:8080' - '--cgroupfs-root=/host/sys/fs/cgroup' - '--wal-dir=/data'这条清单已经体现了 Agent 配置的三大主题：导出目标（--collector-endpoint）、宿主机资源路径（--cgroupfs-root）与本地缓冲（--wal-dir）。
二、四类遥测数据与导出协议
Agent 采集并导出的遥测数据共四类，协议各不相同：
| 遥测类型 | 导出方式 | 典型场景 |
|---|---|---|
| Metrics | Prometheus 文本格式被拉取（Pull），或通过 Prometheus Remote Write 协议推送（Push） | 资源用量、网络、应用层协议指标 |
| Traces | 基于 eBPF 的网络与应用层追踪，经 OTLP/HTTP（OpenTelemetry 协议）发送 | 未接入 OpenTelemetry 的存量服务的链路分析 |
| Logs | 自动发现容器日志并经 OTLP/HTTP 发送 | 容器 stdout/stderr、Journald、/var/log 文件 |
| Profiles | 内置 Pyroscope eBPF profiler 采集 CPU 剖析，经自定义 HTTP 协议发送 | 无侵入的 CPU 热点分析 |
其中 eBPF 追踪能力可以无代码改动地自动识别 HTTP、Postgres、MySQL、Redis、MongoDB、Memcached 等协议（见 eBPF-based tracing）；eBPF 剖析器开箱即用，Java 应用建议追加-XX:+PreserveFramePointer、Node.js 建议追加--perf-basic-prof-only-functions --interpreted-frames-native-stack以提升符号化质量（见 eBPF-based profiling）。
三、配置方式：命令行参数与环境变量
coroot-node-agent支持两种等价的配置方式：命令行 Flag 与同名环境变量。Linux 上二者一一对应；Windows 上环境变量需加COROOT_前缀（详见第四节）。下面按功能域分组整理全部参数（即原文档配置表的完整内容）。
3.1 基础服务与宿主机路径
| Flag | 环境变量 | 默认值 | 说明 |
|---|---|---|---|
--listen | LISTEN | 0.0.0.0:80 | HTTP 监听地址（用于暴露自身/metrics） |
--cgroupfs-root | CGROUPFS_ROOT | /sys/fs/cgroup | 宿主机 cgroup 文件系统根路径；容器内运行时需挂载宿主 cgroup 并指向挂载点（如--cgroupfs-root=/host/sys/fs/cgroup） |
3.2 采集功能开关
| Flag | 环境变量 | 默认值 | 说明 |
|---|---|---|---|
--disable-log-parsing | DISABLE_LOG_PARSING | false | 关闭容器日志解析 |
--disable-json-log-parsing | DISABLE_JSON_LOG_PARSING | false | 关闭从 JSON 格式日志中提取 message、severity 与 attributes |
--disable-pinger | DISABLE_PINGER | false | 关闭对上游的 ICMP ping。关闭后container_net_latency_seconds这类基于 ICMP 往返时延的指标将不可用 |
--disable-l7-tracing | DISABLE_L7_TRACING | false | 关闭应用层（L7）追踪 |
--disable-gpu-monitoring | DISABLE_GPU_MONITORING | false | 关闭 GPU 监控（NVML） |
3.3 运行时插桩与动态分析
| Flag | 环境变量 | 默认值 | 说明 |
|---|---|---|---|
--enable-java-tls | ENABLE_JAVA_TLS | false | 通过动态加载 Agent 开启 Java TLS 插桩 |
--enable-java-async-profiler | ENABLE_JAVA_ASYNC_PROFILER | false | 通过 async-profiler 开启 Java 剖析（CPU、内存分配、锁竞争）。开启后才会产出container_jvm_alloc_bytes_total、container_jvm_lock_contentions_total等指标（见 metrics/node-agent 参考） |
--go-heap-profiler | GO_HEAP_PROFILER | enabled | Go 堆剖析模式：disabled、enabled（被动）或force（对所有 Go 应用强制开启剖析） |
--instrumentation-delay | INSTRUMENTATION_DELAY | 30s | 进程启动后延迟多久再启用 Python GIL 与 Node.js 事件循环插桩 |
--go-heap-profiler=force可确保即使应用自身未开启 profiling 也能采集到 Go 运行时分配数据（container_go_alloc_bytes_total/container_go_alloc_objects_total），在需要全量覆盖的场景下非常实用。
3.4 容器过滤与网络流量控制
| Flag | 环境变量 | 默认值 | 说明 |
|---|---|---|---|
--container-allowlist | CONTAINER_ALLOWLIST | – | 允许采集的容器列表（正则表达式） |
--container-denylist | CONTAINER_DENYLIST | – | 排除采集的容器列表（正则表达式） |
--skip-systemd-system-services | SKIP_SYSTEMD_SYSTEM_SERVICES | true | 跳过已知的 systemd 系统服务（apt、motd、udev 等） |
--exclude-http-requests-by-path | EXCLUDE_HTTP_REQUESTS_BY_PATH | – | 从指标与追踪中排除特定 HTTP 路径（用于过滤健康检查等高频噪音请求） |
--track-public-network | TRACK_PUBLIC_NETWORK | 0.0.0.0/0 | 需要追踪的公网 IP 网段 |
--ephemeral-port-range | EPHEMERAL_PORT_RANGE | 32768-60999 | 从连接追踪中排除的临时端口范围（内核分配的临时端口不属于业务连接） |
3.5 云实例信息标签
这组参数用于向node_cloud_info指标注入云实例信息标签。Agent 本身会通过 sysfs 探测云厂商、调用各家 metadata 服务（AWS、GCP、Azure、Hetzner、Scaleway、DigitalOcean、Alibaba）；对于不支持的云环境，可手动指定（详见 metrics/node-agent 参考 中node_cloud_info一节）。
| Flag | 环境变量 | 默认值 | 说明 |
|---|---|---|---|
--provider | PROVIDER | – | node_cloud_info的provider标签 |
--region | REGION | – | node_cloud_info的region标签 |
--availability-zone | AVAILABILITY_ZONE | – | node_cloud_info的availability_zone标签 |
--instance-type | INSTANCE_TYPE | – | node_cloud_info的instance_type标签 |
--instance-life-cycle | INSTANCE_LIFE_CYCLE | – | node_cloud_info的instance_life_cycle标签 |
3.6 日志采集的速率与基数控制
| Flag | 环境变量 | 默认值 | 说明 |
|---|---|---|---|
--log-per-second | LOG_PER_SECOND | 10.0 | 日志每秒速率限制 |
--log-burst | LOG_BURST | 100 | 日志限流的最大突发量 |
--log-patterns-per-container | LOG_PATTERNS_PER_CONTAINER | 256 | 每个容器每个 level 的最大日志模式数（用于自动日志聚类，对应container_log_messages_total的pattern_hash标签） |
--log-pattern-extraction-limit | LOG_PATTERN_EXTRACTION_LIMIT | 100 | 每秒每个容器用于提取模式的日志条数上限；超限消息计入event was sampled模式（0表示不限） |
日志限流与模式提取限制共同保护了服务端与 ClickHouse 存储，避免高日志量容器造成资源与基数爆炸。所有日志指标都带source（journald/stdout/stderr//var/log路径）、level、pattern_hash、sample标签，便于在 Logs 页面按模式聚合检索。
3.7 指标基数与标签限制
| Flag | 环境变量 | 默认值 | 说明 |
|---|---|---|---|
--max-fqdns-per-container | MAX_FQDNS_PER_CONTAINER | 50 | container_dns_requests_total中每个容器允许的唯一 FQDN 数量上限；超出部分归入domain="~other"桶 |
--max-label-length | MAX_LABEL_LENGTH | 4096 | 指标标签最大长度 |
--max-fqdns-per-container与 3.6 中的模式限制是控制**指标基数（cardinality）**的关键旋钮：DNS 域名与日志模式是典型的高基数来源，通过封顶与~other兜底桶，可以确保大规模集群下 Prometheus/ClickHouse 的序列数量保持可控。
3.8 数据导出：统一端点与分通道端点
| Flag | 环境变量 | 默认值 | 说明 |
|---|---|---|---|
--collector-endpoint | COLLECTOR_ENDPOINT | – | 遥测导出的统一基础 URL |
--api-key | API_KEY | – | Coroot API Key（多项目/多租户场景下用于区分项目） |
--metrics-endpoint | METRICS_ENDPOINT | – | 指标导出的自定义 URL |
--traces-endpoint | TRACES_ENDPOINT | – | 链路导出的自定义 URL |
--traces-sampling | TRACES_SAMPLING | 1.0 | 链路采样率（0.0 ~ 1.0） |
--logs-endpoint | LOGS_ENDPOINT | – | 日志导出的自定义 URL |
--profiles-endpoint | PROFILES_ENDPOINT | – | 剖析数据导出的自定义 URL |
--profiles-prune-fraction | PROFILES_PRUNE_FRACTION | 0.0025 | 丢弃占剖析总量比例低于该值的非关键代码路径（0关闭裁剪） |
--insecure-skip-verify | INSECURE_SKIP_VERIFY | false | 跳过 TLS 证书校验（仅建议在测试环境使用） |
--ca-file | CA_FILE | – | 自定义 CA 证书文件路径（用于自签名证书的采集端场景） |
推荐配置方式：只设置--collector-endpoint+--api-key，让 Agent 把四类数据统一发往 Coroot；仅当需要将某一类数据分流到独立后端（例如把指标发往 VictoriaMetrics、链路发往自有 OTLP Collector）时，才覆盖对应的*_endpoint。在 Coroot 的多租户模式下，Agent 通过 Remote Write 将指标推送至 Coroot，由 Coroot 自动为每个指标附加coroot_project_id标签——这正是--api-key发挥作用的地方。
3.9 采集节奏与本地缓冲
| Flag | 环境变量 | 默认值 | 说明 |
|---|---|---|---|
--scrape-interval | SCRAPE_INTERVAL | 15s | 内部指标采集频率 |
--wal-dir | WAL_DIR | /tmp/coroot-node-agent | WAL 存储目录（容器化部署应挂载持久卷，见 docker-compose 中的/data） |
--max-spool-size | MAX_SPOOL_SIZE | 500MB | 磁盘上 spool 的最大容量 |
WAL 与 spool 提供了「采集与导出解耦」的本地缓冲能力：即使 Coroot 服务端或网络短暂不可用，Agent 也会先把数据写入本地，恢复后再补传，避免数据丢失。
四、Windows 平台：COROOT_ 前缀与平台子集
Windows 版 Agent 复用相同的 Flag，但仅支持平台无关的子集。Linux 专属能力（eBPF L7 追踪与剖析、cgroups、Java/Python/Node.js 插桩、ICMP pinger、systemd 处理、trace/profile 导出）不适用。
关键差异：Flag 名称保持一致（如--scrape-interval），但环境变量一律加COROOT_前缀——因为 Windows 环境变量是全局的，前缀可以避免与其他软件冲突。例如SCRAPE_INTERVAL在 Windows 上写作COROOT_SCRAPE_INTERVAL。
| Flag | 环境变量 | 说明 |
|---|---|---|
--collector-endpoint | COROOT_COLLECTOR_ENDPOINT | Coroot 实例的基础 URL |
--api-key | COROOT_API_KEY | 项目 API Key |
--scrape-interval | COROOT_SCRAPE_INTERVAL | 指标采集间隔 |
--metrics-endpoint/--logs-endpoint | COROOT_METRICS_ENDPOINT/COROOT_LOGS_ENDPOINT | 自定义导出 URL |
--insecure-skip-verify | COROOT_INSECURE_SKIP_VERIFY | 跳过对采集端（collector）的 TLS 校验 |
--ca-file | COROOT_CA_FILE | 自定义 CA 证书路径 |
--disable-log-parsing | COROOT_DISABLE_LOG_PARSING | 关闭 Windows Event Log 与容器日志采集 |
--disable-json-log-parsing | COROOT_DISABLE_JSON_LOG_PARSING | 关闭从 JSON 日志中提取 message、severity、attributes |
--disable-gpu-monitoring | COROOT_DISABLE_GPU_MONITORING | 关闭 NVIDIA GPU 监控 |
--container-allowlist/--container-denylist | COROOT_CONTAINER_ALLOWLIST/COROOT_CONTAINER_DENYLIST | 需要包含 / 排除的服务正则 |
--provider/--region/--availability-zone/--instance-type/--instance-life-cycle | COROOT_PROVIDER等 | 覆盖node_cloud_info标签 |
--wal-dir/--max-spool-size | COROOT_WAL_DIR/COROOT_MAX_SPOOL_SIZE | spool 目录与最大容量 |
--listen | COROOT_LISTEN | 本地/metrics监听地址 |
在 Windows 上通过 MSI 或机器级环境变量设置这些参数，可参考 Windows 安装指南。典型做法是：先用iwr -useb ...install.ps1 | iex以COROOT_COLLECTOR_ENDPOINT/COROOT_API_KEY完成首次安装，随后通过 PowerShell 修改机器级变量并重启服务：
[Environment]::SetEnvironmentVariable("COROOT_SCRAPE_INTERVAL", "30s", "Machine") Restart-Service coroot-windows-agent五、容器级细粒度控制
除了全局配置，还可以在单个容器内部设置环境变量，由 Agent 从容器进程环境中读取，实现逐容器的采集开关（详见 eBPF profiling 文档中关于/proc/<pid>/environ检查机制的说明，见 ebpf-based-profiling.md）：
| 环境变量 | 说明 |
|---|---|
COROOT_EBPF_PROFILING=disabled | 关闭该容器的 eBPF 剖析 |
COROOT_LOG_MONITORING=disabled | 关闭该容器的日志监控与解析 |
COROOT_EBPF_TRACES=disabled | 关闭该容器的 eBPF 链路追踪 |
典型用法是在业务容器的environment中注入这些变量，例如对已知高噪音或敏感的容器显式排除剖析与日志采集，无需重启节点 Agent。
六、安装与部署实战
Docker Compose
最省事的方式是直接复用仓库内的 deploy/docker-compose.yaml：其中node-agent服务已配好 privileged、host PID 与全部挂载，Prometheus 也通过--web.enable-remote-write-receiver开启了 Remote Write 接收端。执行：
curl -fsS https://raw.githubusercontent.com/coroot/coroot/main/deploy/docker-compose.yaml | \ docker compose -f - up -dDocker Swarm
Swarm 不支持 privileged 容器，需要在每个节点手动运行 Agent（见 quick-start/community-edition.md），将NODE_IP替换为集群中任意节点 IP：
docker run --detach --name coroot-node-agent \ --pull=always \ --privileged --pid host \ -v /sys/kernel/tracing:/sys/kernel/tracing:rw \ -v /sys/kernel/debug:/sys/kernel/debug:rw \ -v /sys/fs/cgroup:/host/sys/fs/cgroup:ro \ ghcr.io/coroot/coroot-node-agent \ --cgroupfs-root=/host/sys/fs/cgroup \ --collector-endpoint=http://NODE_IP:8080Ubuntu / Debian 裸机
在安装 Coroot 服务端后，通过官方安装脚本在每个节点部署 Agent（见 ubuntu 安装文档）：
curl -sfL https://raw.githubusercontent.com/coroot/coroot-node-agent/main/install.sh | \ COLLECTOR_ENDPOINT=http://127.0.0.1:8080 \ SCRAPE_INTERVAL=15s \ sh -升级时重跑同一命令即可；卸载可执行/usr/local/bin/coroot-uninstall.sh。
Kubernetes
在 Kubernetes 中 Agent 由 Coroot Operator 以 DaemonSet 形态自动部署到每个节点（见 kubernetes 安装文档），无需手工管理；只要不钉死镜像版本，升级 Coroot 时 Operator 会自动升级 node agent。
七、配置项与指标清单的对应关系
Agent 的配置最终都体现在指标输出上，二者结合阅读效果最佳。完整指标清单见 metrics/node-agent 参考，其中有几条与本文配置项直接呼应：
--disable-pinger↔container_net_latency_seconds（基于 ICMP 往返时延测量）；--max-fqdns-per-container↔container_dns_requests_total的domain标签封顶与~other桶；--enable-java-async-profiler↔container_jvm_alloc_bytes_total、container_jvm_lock_contentions_total等 async-profiler 派生指标；--provider/--region/--availability-zone等 ↔node_cloud_info的provider、region、availability_zone、instance_type、instance_life_cycle标签；--log-pattern-extraction-limit↔container_log_messages_total中event was sampled模式；--cgroupfs-root↔ 全部container_resources_*资源指标（CPU、内存、磁盘，数据来源为 cgroup 各子系统文件）。
八、深入阅读
- 指标全集与标签语义：docs/docs/metrics/node-agent.md
- 组件职责与数据流：docs/docs/installation/architecture.md
- eBPF 追踪能力：docs/docs/tracing/ebpf-based-tracing.md
- eBPF 剖析与运行时符号化：docs/docs/profiling/ebpf-based-profiling.md
- Windows 部署与运维：docs/docs/installation/windows.md
- 指标后端（Prometheus Remote Write / ClickHouse / 多租户）：docs/docs/configuration/prometheus.md
【免费下载链接】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），仅供参考
