Nightingale 集成之 Linux 主机监控：Categraf 内置插件配置实战指南

导读

本文围绕 Nightingale 监控体系中 Linux 主机数据采集这一主题，系统讲解 Categraf 在 Linux 类别下内置插件的配置方法。文章以 integrations/Linux/markdown/README.en_US.md 为核心骨架，逐一展开 cpu、netstat、disk、kernel_vmstat、arp_package、ntp 六个可能需要额外配置的插件，并结合 integrations/Linux/collect/ 目录下的真实配置文件给出可复制的参数说明。读完本文，你将掌握 Linux 主机 CPU、网络连接、磁盘、内核 VM 统计、ARP 报文、NTP 时间偏移等核心指标的采集开关、白名单机制与性能取舍方法，并了解如何配合仓库中的告警规则与仪表盘快速落地监控。

一、Linux 集成概述：开箱即用的采集插件族

在 Nightingale 的集成体系（integrations）中，Linux 是一个覆盖主机基础监控的集成类别。它内置了多个数据采集插件，例如 cpu、mem、net、netstat、kernel_vmstat 等，这些插件大多数默认处于开启状态，安装部署后无需额外配置即可产出指标，因此该集成的工作重心落在“哪些场景需要调参”上。

从仓库目录结构可以清晰看到该集成资产的组成：

• collect/：各插件的采集配置示例，包括 netstat、kernel_vmstat、ntp、arp_packet、processes、sshd、supervisor、node_exporter、logs-agent；
• alerts/：预置告警规则，如 linux_by_categraf.json、Common Alert Rules - Categraf.json，以及分别面向 exporter 与 telegraf 的变体；
• dashboards/：配套仪表盘，如 categraf-overview.json、categraf-detail.json、categraf-processes.json；
• metrics/：指标清单，如 categraf-base.json、exporter-base.json；
• i18n/：国际化文案。

按官方说明，“Nightingale is to monitoring and alerting what Grafana is to visualization”，Categraf 正是 Nightingale 体系中承担指标采集任务的 Agent，Linux 类别下的插件即由 Categraf 在目标主机上执行。下文将围绕 README 中点名的六个需要关注配置的插件逐一深入。

二、cpu 插件：按需开启单核采集

cpu 插件统计 CPU 使用率。默认情况下，它只采集整机（整体）的 CPU 使用情况，不采集每个 CPU Core 的使用情况。这在大多数场景下足以覆盖容量与健康度监控，同时避免指标基数随核数线性膨胀。

如果需要针对每个 CPU 核心分别观测（例如排查单核打满、核间负载不均问题），可以在插件配置中开启：

collect_per_cpu = true

开启后，指标将携带 CPU 核心维度的标签，便于在仪表盘中按核拆分查看。建议在需要深入定位 CPU 热点时开启，常规监控保持默认即可，以控制指标存储成本。

三、netstat 插件：网络连接统计与性能取舍

netstat 插件统计网络连接数，其默认配置如下（与仓库中的 collect/netstat/netstat.toml 完全一致）：

# # collect interval
# interval = 15

disable_summary_stats = false
## if machine has many network connections, use this plugin may exhaust your cpu resource, disable connection stat to avoid this
disable_connection_stats = true

tcp_ext = false
ip_ext = false

各参数含义与建议如下：

参数	默认值	说明
interval	15（注释示例值）	采集周期，单位为秒，按需调整
disable_summary_stats	false	汇总统计开关。默认开启（false 表示“不禁用”），输出类似 ss -s 命令的汇总信息，开销很小，建议保持默认
disable_connection_stats	true	所有连接的详细统计开关。默认关闭（true 表示“禁用”）。在连接数较多的机器上统计每一条连接会明显消耗 CPU 资源，因此默认关闭以规避性能风险
tcp_ext	false	是否读取 /proc/net/netstat 中的 TCP 扩展统计，默认关闭，可开启，这部分不影响性能
ip_ext	false	是否读取 /proc/net/netstat 中的 IP 扩展统计，默认关闭，可开启，同样不影响性能

从源码配置注释可以读出设计者的性能权衡：汇总统计（summary stats）类似 ss -s，开销低，适合默认开启；而逐连接（connection）统计在大连接数场景会耗尽 CPU，因此默认关闭，仅在必要时开启。若机器连接数少、又需要细粒度连接维度数据，可将 disable_connection_stats 改为 false。

四、disk 插件：磁盘使用率采集与过滤规则

disk 插件统计磁盘使用率，默认配置如下：

# 严格指定要采集的挂载点，如果指定了，就只采集指定的挂载点
# mount_points = ["/"]

# 有些 fstype 没必要采集，可以忽略
ignore_fs = ["tmpfs", "devtmpfs", "devfs", "iso9660", "overlay", "aufs", "squashfs", "nsfs", "CDFS", "fuse.juicefs"]

# 有些挂载点没必要采集，可以忽略，这里可以配置前缀，符合前缀的挂载点都会被忽略
ignore_mount_points = ["/boot", "/var/lib/kubelet/pods"]

三个关键参数：

• mount_points（可选，默认注释）：严格白名单。一旦指定，插件只采集列表中给出的挂载点。典型用法是仅保留根分区 ["/"]，避免大量无关挂载点造成的指标噪音。默认不指定，即采集所有可见挂载点。
• ignore_fs（默认已配置）：按文件系统类型（fstype）忽略。列表中的 tmpfs、devtmpfs、devfs、iso9660、overlay、aufs、squashfs、nsfs、CDFS、fuse.juicefs 等多为临时、虚拟或只读文件系统，磁盘使用率统计意义不大，故默认忽略。若你的环境有特殊文件系统（例如某些分布式存储 FUSE 挂载点确实需要监控），可按需增删。
• ignore_mount_points（默认已配置）：按挂载点前缀忽略。示例中的 /boot 与 /var/lib/kubelet/pods 分别是引导分区和 Kubernetes Pod 卷目录，前者空间固定、后者随 Pod 生命周期频繁变化，均不适合作为磁盘使用率告警依据。该参数匹配的是前缀，任何命中前缀的挂载点都会被忽略。

五、kernel_vmstat 插件：/proc/vmstat 白名单采集

kernel_vmstat 插件的统计数据来自 /proc/vmstat，该文件仅在高版本内核上支持。/proc/vmstat 内容条目非常多，如果全部采集会产生大量指标，因此插件默认只采集 oom_kill 次数（内存耗尽触发 OOM Killer 杀进程的次数），其他指标均不采集。

如果需要打开其他采集项，只需修改配置中的 white_list 部分。仓库中 collect/kernel_vmstat/kernel_vmstat.toml 给出了完整白名单模板（共百余个字段），README 摘录如下供参考：

# file: /proc/vmstat
[white_list]
oom_kill = 1
nr_free_pages = 0
nr_alloc_batch = 0
# 其他字段按需添加

使用方式非常直观：

• 值设为 1 表示采集该字段；
• 值设为 0 表示不采集该字段；
• 其他字段按需添加，例如 pgpgin（换入页数）、pswpin（换入次数）、nr_dirty（脏页数）、thp_fault_alloc（透明大页分配次数）等。

从仓库完整配置可见，模板已覆盖 nr_ 系列（内存页统计）、numa_ 系列（NUMA 命中与迁移）、pg 系列（分页活动）、compact_ 系列（内存压缩）、unevictable_ 系列（不可回收页）、thp_ 系列（透明大页）等大量字段，字段名与 /proc/vmstat 输出保持一致，可放心按需启用。该插件适合在内核内存调优、OOM 排查、NUMA 与页回收行为分析等场景下针对性开放采集项。

六、arp_package 插件：ARP 包统计与 cgo 依赖

arp_package 插件统计 ARP（Address Resolution Protocol）包的数量，用于观测二层网络的广播/请求流量。该插件依赖 cgo，因此在常规构建中默认不包含。

如果需要启用该插件，需要下载带 with-cgo 标签的 Categraf 发布包。仓库中对应的采集配置为 collect/arp_packet/arp_packet.toml：

# # collect interval
# interval = 15

[[instances]]
#eth_device="ens192"

配置要点：

• interval：采集周期（秒），注释示例为 15；
• instances.eth_device：可指定网络设备（如 ens192），用于限定在特定网卡上统计 ARP 报文；不指定时按默认行为统计。

注意：插件目录名为 arp_packet（文件 arp_packet.toml），与文档中的插件名 arp_package 存在命名差异，配置时以仓库实际目录文件为准。由于依赖 cgo，交叉编译或精简发布包中不会包含该插件，务必选择 with-cgo 版本。

七、ntp 插件：机器时间偏移监控

ntp 插件用于监控机器的时间偏移量，其工作方式是：只需提供 NTP 服务端地址，Categraf 就会周期性向该服务器发起请求，将返回时间与本机时间对比，计算出偏移量并上报。

监控指标名为 ntp_offset_ms，单位是毫秒。一般来说，该值不应超过 1000（即 1 秒）；超过该阈值说明本机时钟漂移明显，可能影响日志时间戳、告警判定、分布式系统一致性等，需要及时通过 NTP 服务校准。

仓库中 collect/ntp/ntp.toml 给出完整配置模板：

# # collect interval
# interval = 15

# # ntp servers
# ntp_servers = ["ntp.aliyun.com"]

# # response time out seconds
# timeout = 5

参数说明：

参数	默认/示例	说明
interval	15（注释示例值）	采集周期，秒
ntp_servers	["ntp.aliyun.com"]	NTP 服务端地址列表，可配置多个服务器；生产环境建议使用内网 NTP 服务器以保证可达性与精度
timeout	5	单次请求的超时时间，秒

落地实践上，可结合 ntp_offset_ms 配置告警规则：当偏移量绝对值超过 1000ms 时触发告警，即可提前发现时钟漂移问题。

八、配套资产：告警规则、仪表盘与更多采集插件

除 README 重点讲解的六个插件外，Linux 集成还提供了开箱即用的配套资产，帮助用户快速完成从采集到告警、可视化的闭环：

• 告警规则：alerts/ 目录下的 linux_by_categraf.json 针对 Categraf 采集的指标预置了告警规则，另有 Common Alert Rules - Categraf.json 提供通用告警模板，以及面向 linux_by_exporter.json（exporter 采集）与 linux_by_telegraf.json（telegraf 采集）的变体，可按采集器选型导入对应规则。
• 仪表盘：dashboards/ 提供 categraf-overview.json（总览）、categraf-detail.json（详情）、categraf-processes.json（进程）等仪表盘，导入后即可直观查看主机指标。
• 指标清单：metrics/ 中的 categraf-base.json 与 exporter-base.json 汇总了基础指标定义，便于理解插件输出与命名。

此外，collect/ 中还包含若干同样可配置的插件示例，可作为进一步调参的参考：

• processes（processes.toml）：进程采集，可配置 force_ps（强制使用 ps 命令采集）与 force_proc（强制使用 /proc 采集），默认由插件自行选择采集方式。
• sshd（sshd.toml）：SSH 登录审计，可配置 labels 附加标签、enable_username（是否在指标中携带 username 标签）、enable_ip（是否携带 client_ip 标签），适合安全审计场景。
• supervisor（supervisor.toml）：通过 Supervisor 的 XML-RPC API 采集其管理的进程信息，可配置 url（如 http://login:pass@localhost:9001/RPC2）、metrics_include / metrics_exclude 控制附加指标（pid、rc）的采集范围。
• node_exporter（node_exporter.toml）：内置 node_exporter 采集能力，通过 collectors 参数按需启用/禁用各 collector（如 cpu、meminfo、filesystem、netstat、vmstat 等），relabel_configs 支持标签改写。
• logs-agent（logs-agent.toml）：日志采集配置，支持 send_to、send_type（http/tcp/kafka）、topic、批量发送参数（batch_wait、batch_max_size、batch_max_concurrence）、Kafka SASL 认证（sasl_enable 等）、容器日志采集（enable_collect_container）以及 logs.items 单条日志规则（type 为 file/journald/tcp/udp，path、source、service 等字段）。

九、小结

Linux 集成是 Nightingale + Categraf 体系中基础且高频的监控入口。大多数插件默认开启、无需配置即可采集整机 CPU、内存、网络、磁盘等核心指标；真正需要介入的配置点集中在本文展开的六处：CPU 单核采集开关、netstat 的逐连接统计与性能取舍、disk 的挂载点/文件系统过滤、kernel_vmstat 的白名单式按需采集、arp_package 的 cgo 依赖选型，以及 ntp 的时间偏移监控。结合 alerts/ 预置告警规则与 dashboards/ 仪表盘，可以在几分钟内完成一台 Linux 主机的标准化监控落地；而对性能敏感或指标量敏感的场景，本文给出的各参数默认值与取舍建议可直接作为调优依据。