Collectd 常用 CLI 命令与排障详解

目标：把 collectd 全家桶的命令行工具逐一讲清并配真实回显——守护进程参数、collectdctl 查询控制、collectd-nagios 三态检查、collectd-tg 压测数据生成、collectdmon 看护，再沉淀一套「插件加载/日志/数据落盘」的排查方法与常见错误排障实录。已在 Ubuntu 22.04 服务器（collectd 5.12.0-10ubuntu0.1）逐条实测通过。

一、环境信息

操作系统：Ubuntu 22.04 LTS（jammy），amd64 架构
collectd 版本：5.12.0-10ubuntu0.1（apt 安装）
工具来源：collectd 包提供 /usr/sbin/collectd 与 /usr/sbin/collectdmon；collectd-utils 包提供 /usr/bin/collectdctl、/usr/bin/collectd-nagios、/usr/bin/collectd-tg（dpkg -L 实查）
主配置文件：/etc/collectd/collectd.conf
unixsock 套接字：/var/run/collectd-unixsock（已启用 unixsock 插件，SocketPerms 0660）
数据目录：/var/lib/collectd/rrd/collectd-server/（主机名 collectd-server）

二、工具概览

collectd 的运维界面由「1 个守护进程 + 4 个工具 + systemd 套件」组成：

命令	所属包	用途
collectd	collectd	守护进程本体，兼做配置自检（-t/-T）与前台调试（-f）
collectdctl	collectd-utils	通过 unixsock 实时查询/注入/刷写指标值
collectd-nagios	collectd-utils	按告警阈值查询指标，输出 Nagios 兼容结果与退出码
collectd-tg	collectd-utils	生成模拟指标流量，压测 collectd 网络接收端
collectdmon	collectd	守护进程看护器：collectd 退出后自动拉起
systemctl / journalctl	systemd	服务启停与日志检索

表解读：日常排障的主链路是 journalctl（看日志）→ collectd -t（查语法）→ collectdctl（看实时值）三件套；collectd-nagios 用于把 collectd 的指标接进 Nagios 告警；collectd-tg/collectdmon 属于进阶工具。

三、前置条件

collectd 与 collectd-utils 已安装（《Ubuntu 22.04 安装 Collectd 指南》）；
服务运行中：systemctl is-active collectd → active；
collectdctl/collectd-nagios 需要已启用 unixsock 插件（collectd.conf 中 LoadPlugin unixsock 且套接字存在）：

ls -la /var/run/collectd-unixsock

实测回显：

srw-rw---- 1 root root 0 Oct 30 14:41 /var/run/collectd-unixsock

部分 collectdctl 操作需要 root（或与套接字同组）权限，本文命令均以 root 执行。

四、collectd 守护进程本体详解

collectd 二进制的全部选项如下（collectd -h 实测全文）：

Usage: collectd [OPTIONS]

Available options:
  General:
    -C <file>       Configuration file.
                    Default: /etc/collectd/collectd.conf
    -t              Test config and exit.
    -T              Test plugin read and exit.
    -P <file>       PID-file.
                    Default: /var/run/collectd.pid
    -f              Don't fork to the background.
    -B              Don't create the BaseDir
    -h              Display help (this message)

Builtin defaults:
  Config file       /etc/collectd/collectd.conf
  PID file          /var/run/collectd.pid
  Plugin directory  /usr/lib/collectd
  Data directory    /var/lib/collectd

collectd 5.12.0.git, http://collectd.org/
by Florian octo Forster <octo@collectd.org>
for contributions see `AUTHORS'

（横幅显示 collectd 5.12.0.git 是 Ubuntu 从 git 快照打包的构建标识，包版本以 dpkg -l collectd 的 5.12.0-10ubuntu0.1 为准。）

各选项用法与实测：

-C <file>：指定配置文件。与 -t/-T/-f 组合可测试任意配置而不影响运行中的服务：

# 用临时配置做语法测试
printf 'Hostname "cfgtest"\nInterval 10\n' > /tmp/cfgtest.conf
collectd -C /tmp/cfgtest.conf -t
echo $?

实测回显：

-t：测试配置并退出。只解析语法，无输出、退出码 0 即通过。⚠️ 边界（实测验证过的两个盲区）：
- 查不出不存在的插件：配置写 LoadPlugin foobarbaz 后 -t 仍是退出码 0 无输出，前台运行才报错（见第十章 10.1）；
- 查不出 TypesDB 路径错误（见第十章 10.2）。
-T：测试插件读取并退出。让每个已加载读插件执行一次 read 后退出，退出码 0 即读取无异常：

collectd -T
echo $?

实测回显：

-f：前台运行不 fork。调试神器——把错误直接打到终端：

# 前台跑 3 秒观察输出（Ctrl+C 或超时结束）
timeout 3 collectd -f 2>&1 | head -4

实测回显：

Initialization complete, entering read-loop.
Exiting normally.

-P <file>：指定 PID 文件，多实例隔离时用；-B：不自动创建 BaseDir，避免以 root 误建目录。

五、collectdctl 详解：实时查询与注入

collectdctl 通过 unixsock 与守护进程对话，能实时查值、注入值、触发刷盘。无参数运行看用法：

collectdctl 2>&1

实测回显（全文）：

collectdctl: missing command
Usage: collectdctl [options] <command> [cmd options]

Available options:
  -s       Path to collectd's UNIX socket.
           Default: /var/run/collectd-unixsock

  -h       Display this help and exit.

5.1 listval：列出值缓存中的全部标识

collectdctl -s /var/run/collectd-unixsock listval | head -12

实测回显（输出节选，实测首部）：

collectd-server/df-etc-hostname/df_complex-free
collectd-server/df-etc-hostname/df_complex-reserved
collectd-server/df-etc-hostname/df_complex-used
collectd-server/df-etc-hosts/df_complex-free
collectd-server/df-etc-hosts/df_complex-reserved
collectd-server/df-etc-hosts/df_complex-used
collectd-server/df-etc-resolv.conf/df_complex-free
collectd-server/df-etc-resolv.conf/df_complex-reserved
collectd-server/df-etc-resolv.conf/df_complex-used
collectd-server/df-root/df_complex-free
collectd-server/df-root/df_complex-reserved
collectd-server/df-root/df_complex-used

# 统计缓存中的标识总数
collectdctl -s /var/run/collectd-unixsock listval | wc -l

实测回显：

标识格式即五元组 host/plugin[-instance]/type[-instance]。listval 是「采集是否真的在发生」的第一验证手段——改完配置重启后，listval 里出现新标识才算数。

5.2 getval：按标识查询最新值

collectdctl -s /var/run/collectd-unixsock getval collectd-server/load/load

实测回显：

shortterm=1.732422e+00
midterm=1.896484e+00
longterm=1.704590e+00

collectdctl -s /var/run/collectd-unixsock getval collectd-server/memory/percent-used

实测回显：

value=5.059611e+01

（memory/percent-used 即配置 ValuesPercentage true 后的内存使用百分比，约 50.6%。）

5.3 putval/getval：注入与读回（闭环实测）

putval 把外部数据注入值缓存，标识与 interval 可自定义，N: 表示用当前时间戳：

# 注入一个自定义 gauge 值 42.5
collectdctl -s /var/run/collectd-unixsock putval collectd-server/gauge-test/gauge-demo interval=10 N:42.5
echo $?
# 立即读回验证
collectdctl -s /var/run/collectd-unixsock getval collectd-server/gauge-test/gauge-demo

实测回显：

0
value=4.250000e+01

注入的标识同样出现在 listval 里（collectd-server/gauge-test/gauge-demo）。配合 exec 插件可以把任意脚本数据喂进 collectd 管道。⚠️ 注意：putval 的 type 必须存在于 TypesDB（gauge 是内置类型）；写不存在的类型会报 Type 'xxx' is unknown.（见 5.5）。

5.4 flush：强制刷写

让写插件立刻把缓存数据落盘（rrdtool 默认缓存 120 秒）：

collectdctl -s /var/run/collectd-unixsock flush
echo $?

实测回显：

可带参数限定范围：flush timeout=2（只刷超过 2 秒未写的）、flush plugin=rrdtool identifier=collectd-server/load/load（只刷某个标识）。

5.5 错误分支实测

# 套接字不存在
collectdctl -s /var/run/no-sock listval
echo $?

实测回显：

ERROR: Failed to connect to daemon at unix:/var/run/no-sock: No such file or directory.
1

# 查询不存在的类型
collectdctl -s /var/run/collectd-unixsock getval collectd-server/nosuch/none
echo $?

实测回显：

ERROR: Server error: Type `none' is unknown.
255

两类错误对应两种根因：连接失败是「服务没起/unixsock 没开/路径不对」；Type unknown 是「标识里的 type 不在 TypesDB」——putval/getval 前先 grep 'gauge' /usr/share/collectd/types.db 确认类型存在。

六、collectd-nagios 详解：三态检查

collectd-nagios 从 unixsock 取值并按 warning/critical 阈值输出 Nagios 兼容结果。无参数运行看用法：

collectd-nagios 2>&1

实测回显（全文）：

Missing required arguments.
Usage: collectd-nagios <-s socket> <-n value_spec> <-H hostname> [options]

Valid options are:
  -s <socket>    Path to collectd's UNIX-socket.
  -n <v_spec>    Value specification to get from collectd.
                 Format: `plugin-instance/type-instance'
  -d <ds>        Select the DS to examine. May be repeated to examine multiple
                 DSes. By default all DSes are used.
  -g <consol>    Method to use to consolidate several DSes.
                 See below for a list of valid arguments.
  -H <host>      Hostname to query the values for.
  -c <range>     Critical range
  -w <range>     Warning range
  -m             Treat "Not a Number" (NaN) as critical (default: warning)

6.1 正常检查（OKAY）

collectd-nagios -s /var/run/collectd-unixsock -H collectd-server -n load/load -d shortterm -w 2.5 -c 5
echo EXIT=$?

实测回显：

OKAY: 0 critical, 0 warning, 1 okay | shortterm=1.523438;;;;
EXIT=0

6.2 越限检查（WARNING/CRITICAL）

把告警线压到当前值以下即可复现 WARNING（值不变，阈值变化）：

collectd-nagios -s /var/run/collectd-unixsock -H collectd-server -n load/load -d shortterm -w 0.5 -c 5
echo EXIT=$?

实测回显：

WARNING: 0 critical, 1 warning, 0 okay | shortterm=1.523438;;;;
EXIT=1

退出码约定与 Nagios 插件规范一致：0=OKAY、1=WARNING、2=CRITICAL、3=UNKNOWN。查询不存在的类型时按 CRITICAL 处理：

collectd-nagios -s /var/run/collectd-unixsock -H collectd-server -n nosuch/none -w 1 -c 2
echo EXIT=$?

实测回显：

ERROR: Retrieving values from the daemon failed: Server error: Type `none' is unknown..
2

-w/-c 支持区间语法（如 -w 0.5:2.5 低于 0.5 或高于 2.5 告警），-g 指定多 DS 聚合方式（average/sum/min/max 等）。接入 Nagios 时把本命令配置成 check_command 即可。

七、collectd-tg 详解：压测数据生成

collectd-tg 模拟多主机多插件的指标流，用来压测 collectd 的 network 接收端。用法全文（collectd-tg -h 实测）：

collectd-tg -- collectd traffic generator

  Usage: collectd-ng [OPTION]

  Valid options:
    -n <number>    Number of value lists. (Default: 100000)
    -H <number>    Number of hosts to emulate. (Default: 1000)
    -p <number>    Number of plugins to emulate. (Default: 20)
    -i <seconds>   Interval of each value in seconds. (Default: 10.000)
    -d <dest>      Destination address of the network packets.
                   (Default: ff18::efc0:4a42)
    -D <port>      Destination port of the network packets.
                   (Default: 25826)
    -h             Print usage information (this output).

💡 说明：Usage 行里的 collectd-ng 是 5.12.0 二进制自带的拼写瑕疵，实查原样照抄（不影响功能）。-d 默认地址是 collectd network 插件约定的多播组，-D 默认 25826 是 network 插件端口；-H/-p 都是「模拟多少个」的数字，不是主机名/插件名——实测传字符串会报错：

collectd-tg -n 1 -H tg-host

实测回显：

Unable to parse option as a number: "tg-host"

运行实测（默认参数生成 10 万条值列表后持续发送，用 timeout 截取前几秒）：

timeout 3 collectd-tg

实测回显（输出节选，实测首部）：

Creating 100000 values ... done
0 values have been sent.
1 values have been sent.
2 values have been sent.
3 values have been sent.

⚠️ 注意：collectd-tg 发送的是 network 二进制协议（UDP 25826），压测目标端要开 LoadPlugin network + <Plugin network> Listen "..." </Plugin> 才能收下；它是真实 UDP 流量，不要对着生产接收端裸跑。

八、collectdmon 详解：进程看护

collectdmon 包一层 collectd，子进程退出后自动重启之。用法全文（collectdmon -h 实测）：

Usage: collectdmon <options> [-- <collectd options>]

Available options:
  -h         Display this help and exit.
  -c <path>  Path to the collectd binary.
  -P <file>  PID-file.

For <collectd options> see collectd.conf(5).

collectd 5.12.0.git, http://collectd.org/

典型用法：collectdmon -P /var/run/collectdmon.pid -- -C /etc/collectd/collectd.conf——collectdmon 自身转后台，collectd 崩溃即被拉起。systemd 场景下单元已配 Restart=on-failure，无需再叠 collectdmon；它主要服务 sysvinit/手工启动的老环境。

九、运行状态与日志排查方法

9.1 服务与日志三连

systemctl is-active collectd
systemctl is-enabled collectd
journalctl -u collectd --no-pager -n 20 -o cat

实测回显（本机累计启动多次，插件加载计数）：

active
enabled

# 统计历史日志中插件加载成功记录条数
journalctl -u collectd -o cat | grep -c "successfully loaded"

实测回显：

日志关键词速查：plugin_load: plugin "cpu" successfully loaded.（逐插件加载成功）、Systemd detected, trying to signal readiness.（Type=notify 就绪握手）、Initialization complete, entering read-loop.（进入主循环=启动成功）、Error: Parsing the config file failed!（配置致命错误）。

9.2 数据落盘核对（mtime 法）

「采集是否在发生」的物理证据是 RRD 文件修改时间持续前进：

date +%T
stat -c "%y %n" /var/lib/collectd/rrd/collectd-server/load/load.rrd

实测回显（两行时间差应≈Interval）：

14:40:49
14:40:48 /var/lib/collectd/rrd/collectd-server/load/load.rrd

配合 5.1 的 listval（内存缓存侧）与 rrd 目录清单（磁盘侧），可以判定数据链路断在哪一环：listval 有值而 rrd 不更新 → 写插件问题；listval 没值 → 读插件/Interval 问题。

9.3 配置自检的正确姿势

# 语法层
collectd -t
# 读取层（执行一轮全部读插件的 read）
collectd -T
# 运行层
systemctl restart collectd && sleep 12 && journalctl -u collectd -o cat | tail -8

三层各司其职：-t 查语法、-T 查读取、日志查加载与运行。⚠️ -t 的盲区清单见第十章。

十、常见错误排障实录

以下六例均为本机 5.12.0 实测复现的原始错误输出，按「现象 → 根因 → 处置」整理。

10.1 LoadPlugin 写了不存在的插件

现象：collectd -t 静默通过（退出码 0），启动失败。前台运行暴露真实错误：

plugin_load: Could not find plugin "foobarbaz" in /usr/lib/collectd
Error: Parsing the config file failed!

根因：-t 只解析语法不加载插件；插件存在性在加载阶段检查。处置：ls /usr/lib/collectd/<名字>.so 先确认插件文件存在再 LoadPlugin；Ubuntu 里缺插件通常意味着要装对应的 collectd 子包（如 collectd-dev、插件集包）或换方案 B 编译。

10.2 TypesDB 路径错误

现象：服务能启动但持续告警：

Failed to open types database `/usr/share/collectd/types_missing.db': No such file or directory.
Failed to open types database `/usr/share/collectd/types_missing.db': No such file or directory
Initialization complete, entering read-loop.

根因：TypesDB 是全部指标的类型字典，打不开则所有上报值无处注册。后果：服务活着但 collectdctl listval 无新值、RRD 停止增长。处置：修正路径（ls -la $路径 核对）；自定义 TypesDB 时保留原文件路径并追加新行，不要整文件替换。

10.3 unixsock 套接字属组告警

现象：日志出现且套接字照常创建：

unixsock plugin: No such group: `collectd'

根因：SocketGroup 默认 collectd 组，系统不存在该组。影响：套接字落为 root:root，仅 root 可读写；非 root 运行的 collectdctl 会 Permission denied。处置：groupadd collectd 并在插件块显式 SocketGroup "collectd"，或把 SocketGroup 指向既有组。

10.4 write_graphite 目标不可达

现象：服务保持 active，日志刷错误（实测目标改为不存在域名）：

write_graphite plugin: getaddrinfo (nosuchhost.invalid, 2003, tcp) failed: Name or service not known

根因：写插件连接失败是可恢复错误，collectd 不会因此退出，恢复网络后自动续传（仅缓存窗口内）。处置：getent hosts <目标> 先验证 DNS；只看 systemctl is-active 会误以为一切正常，转发健康度要靠接收端流量或日志监控。

10.5 全局选项拼写错误被静默忽略

现象：把 Interval 误写成 IntervalX 10，前台启动零警告：

Initialization complete, entering read-loop.

根因：collectd 对未知全局指令不报错（静默丢弃）。后果：以为改了 10 秒实际还是默认值。处置：改 Interval 后用 mtime 步进法验证真实间隔（见 9.2）；配置变更坚持「小步改 + 立即验证」。

10.6 collectdctl 连接失败家族

实测两种报错与对应根因：

ERROR: Failed to connect to daemon at unix:/var/run/no-sock: No such file or directory.

→ 套接字路径错或 unixsock 插件未启用（ls /var/run/collectd-unixsock + 配置核对）。

ERROR: Server error: Type `none' is unknown.

→ 标识中的 type 不在 TypesDB；getval/putval 前用 grep '<type>' /usr/share/collectd/types.db 确认。

十一、注意事项

-t/-T 是分层自检：-t 语法、-T 读取、日志看加载，三层都过才算配置健康，别只跑 -t；
unixsock 是工具面开关：collectdctl/collectd-nagios 全部依赖它，最小化安装后想用工具先加插件；
collectd-tg 是真实流量：默认 10 万条值列表 × 持续发送，对准生产接收端前先想清楚；
值缓存有界：listval 的标识数随插件与实例数增长，长期异常增长（如 putval 注入失控）要警惕内存；
退出码契约：collectd-nagios 的 0/1/2/3 与 collectdctl 的 0/1/255 都要进脚本判断，别只看 stdout。

十二、常见问题（FAQ）

Q1：collectdctl 报 Permission denied，但命令明明没错？ 套接字权限是 0660 root:root（SocketPerms 默认），非 root 用户需加入套接字属组（SocketGroup 指定组）或用 sudo 执行。

Q2：putval 注入的值会写进 RRD 吗？ 会。putval 注入值缓存后走正常写插件管道，对应标识的 RRD 会随之建文件（需类型在 TypesDB）。测试注入建议用独立标识（如 gauge-test），避免污染真实指标目录。

Q3：怎么快速确认某个插件采集正常？ 三步：journalctl -u collectd -o cat | grep '<插件名>' 看加载；collectdctl ... listval | grep <插件名> 看值缓存有无该插件标识；stat 对应 RRD 目录看 mtime 是否前进。三关全过即正常。

十三、参考链接

collectd 手册首页（文档总目录）：https://collectd.org/documentation.shtml
collectd Wiki（插件与机制）：https://collectd.org/wiki/index.php/Table_of_Plugins
Notifications and thresholds（阈值与通知机制）：https://collectd.org/wiki/index.php/Notifications_and_thresholds
本专栏姊妹篇：《Ubuntu 22.04 安装 Collectd 指南》、《Collectd 配置参数详解》、《Collectd 介绍与选型指南》