Categraf 监控采集器常见问题汇总

巴辉特 2025-12-15 14:22:18

总结一下社区常见的问题，供大家参考。不过在描述具体问题之前，请先了解 Categraf 的核心职能：

采集监控指标

在即时查询里可以看到机器各个指标的历史趋势图，就是 Categraf 采集的监控指标。比如：

如果这个页面查不到机器的历史监控数据，说明采集、上报、存储链路出了问题。

上报机器元信息

机器列表里的机器，会呈现一些字段，比如更新时间、时间偏移、内存、CPU 等字段，都是通过 Categraf 上报的元信息拿到的。

点击某个机器，会展开侧拉板，侧拉板里会呈现机器的元信息：

执行自愈脚本

一些日常运维工作需要批量对一批机器执行脚本，或者某个机器报警了，想要自动去机器上跑一个脚本。

hostname 配置

Categraf 要想达成上面所述的功能，需要有一个唯一标识，用以区分不同的机器。这个唯一标识就是 conf/config.toml 配置文件中的 hostname 配置。

# add label(agent_hostname) to series
# "" -> auto detect hostname
# "xx" -> use specified string xx
# "$hostname" -> auto detect hostname
# "$ip" -> auto detect ip
# "$hostname-$ip" -> auto detect hostname and ip to replace the vars
hostname = ""

上面的注释其实也说得很清楚了，我这里也再啰嗦一下。

hostname 字段用户配置成啥，就以啥作为机器标识。所以，不同机器一定要配置为不同的字符串。

但是每个机器都要配置一个不同的字符串，有点费劲，能否自动设置为本机的机器名？可以的，这个字段如果留空，就会自动获取本机的机器名。

有些公司机器名可能会重复，想要自动设置为本机 IP，也可以，那就配置为：

hostname = "$ip"

Categraf 发现用户配置的是 $ip，就会自动探测本机 IP 填充进去，不过你要检查一下最终探测到的 IP 是不是对的，怎么检查？测试采集一下指标，看看输出即可：

[root@iZ2ze4oi71k3qgdxwsyn07Z categraf-v0.4.20-linux-amd64]# ./categraf --test --inputs mem 2>/dev/null| grep mem_
1762167444 18:57:24 mem_high_free agent_hostname=10.99.1.107 0
1762167444 18:57:24 mem_huge_pages_free agent_hostname=10.99.1.107 0

hostname 的信息会体现为指标里的 agent_hostname 标签，如上，我的本机 IP 自动探测为 10.99.1.107。

有时想从环境变量里获取，也可以，也是使用 $ 符号引用环境变量的名称即可，比如：

[root@iZ2ze4oi71k3qgdxwsyn07Z categraf-v0.4.20-linux-amd64]# export HOST=hello007
[root@iZ2ze4oi71k3qgdxwsyn07Z categraf-v0.4.20-linux-amd64]# grep HOST conf/config.toml
hostname = "$HOST"
[root@iZ2ze4oi71k3qgdxwsyn07Z categraf-v0.4.20-linux-amd64]# ./categraf --test --inputs mem 2>/dev/null| grep mem_
1762167642 19:00:42 mem_active agent_hostname=hello007 1265184768
1762167642 19:00:42 mem_huge_page_size agent_hostname=hello007 2097152

如上，我设置了一个环境变量 HOST=hello007，然后在配置文件里通过 hostname="$HOST" 做了引用。最终通过 --test 看到的就是 agent_hostname=hello007 标签。

⚠️ 注意：

如果 config.toml 里配置里 omit_hostname = true 上报的监控数据中就没有 agent_hostname 标签了
Categraf 的监控数据如果发给夜莺，夜莺会把 agent_hostname 标签重命名为 ident

writers 配置

配置段样例如下：

[[writers]]
url = "http://nightingale:17000/prometheus/v1/write"
basic_auth_user = ""
basic_auth_pass = ""
timeout = 5000
dial_timeout = 2500
max_idle_conns_per_host = 100

Categraf 采集了监控数据之后，就是推送给 writers 指定的 url，通常是推送给夜莺，所以 url 配置为夜莺的地址。

如果使用了边缘模式，边缘机房的 Categraf 要配置为边缘 n9e-edge 的地址。

如果要做高可用，应该在夜莺前面架设负载均衡，Categraf 这里配置负载均衡的地址。Categraf 这里不支持写多个夜莺的 IP。

⚠️ 如果你们不用夜莺，只用 Categraf，也可以把 writers 的 url 配置为时序库的 remote write 地址。Categraf 使用 Prometheus remote write 协议推送监控数据。

writers 部分是使用双中括号括起来的，这在 toml 语法中表示数组，即可以配置多个 writer 地址，比如：

[[writers]]
url = "http://ip1:17000/prometheus/v1/write"
basic_auth_user = ""
basic_auth_pass = ""
timeout = 5000
dial_timeout = 2500
max_idle_conns_per_host = 100
[[writers]]
url = "http://ip2:17000/prometheus/v1/write"
basic_auth_user = ""
basic_auth_pass = ""
timeout = 5000
dial_timeout = 2500
max_idle_conns_per_host = 100

Categraf 会把采集到的数据分别推送给这两个 writer。其中一个 writer 慢了可能也会影响另一个。通常，这个双写的功能应该用不到。

heartbeat 配置

Categraf 采集了机器元信息，推送给 heartbeat 配置的 url。必须配置为夜莺的地址。如果用到了边缘的 n9e-edge，则配置为 n9e-edge 的地址。

如果这个地址配置的不对或没有 enable，机器列表就是空的，或者即便机器列表不为空，机器后面的各个字段都是 unknown，页面上点击机器标识展开的侧拉板里也看不到机器的元信息。

机器的元信息发给夜莺之后，夜莺是存储在 redis 中的。

如果不用夜莺，只用 Categraf 的采集能力，heartbeat 可以关闭，即设置 enable = false。

ibex 配置

ibex 是执行脚本的，告警自愈脚本就是通过 ibex 执行的。如果你们担心安全性，就不要启用 ibex 了。

ibex 下面有个 servers 配置，是配置夜莺的 rpc 地址，默认夜莺 rpc server 会监听在 20090 端口，如果是边缘模式，则配置为边缘 n9e-edge 的 rpc 端口。

注意，这个是走的四层不是七层。如果要做高可用，把多个夜莺 server 的地址配置到 servers 配置里即可，servers 的 value 是个数组，比如：

servers = ["ip1:20090", "ip2:20090"]

多个监控目标的问题

Categraf 有很多监控插件，每个监控插件有自己的配置，在 conf 目录下有一堆 input. 打头的目录，就是一个一个的插件配置目录。

比如 mysql 的配置文件：conf/input.mysql/mysql.toml：

[[instances]]
address = "127.0.0.1:3306"
username = "categraf"
password = "XXXXXXXX"

但凡你看到插件的配置里有 [[instances]] 就说明，可以配置多个监控目标，比如要监控两个 mysql 实例：

[[instances]]
address = "10.1.2.3:3306"
username = "categraf"
password = "XXXXXXXX"
[[instances]]
address = "10.1.2.4:3306"
username = "categraf"
password = "XXXXXXXX"

采集频率问题

在插件里，最开始的位置通常有个 interval = 15 的配置，表示这个插件的所有 instance 都是 15s 采集一次，如果这个配置注释了，那就是复用全局的 interval，全局的 interval 在 conf/config.toml 里。

如果第一个实例希望 15s 采集一次，第二个实例 30s 采集一次，可以这么配置：

interval = 15
[[instances]]
address = "10.1.2.3:3306"
username = "categraf"
password = "XXXXXXXX"
interval_times = 1
[[instances]]
address = "10.1.2.4:3306"
username = "categraf"
password = "XXXXXXXX"
interval_times = 2

通过 interval_times 来控制，这个实例的采集频率等于：

interval * interval_times

那如果我想更频繁，不是 15s 的倍数怎么办？简单，直接把 interval 设置为 1，1 乘以任何数都是原来的数，那就变相使用 interval_times 来控制了。比如：

interval = 1
[[instances]]
address = "10.1.2.3:3306"
username = "categraf"
password = "XXXXXXXX"
interval_times = 7
[[instances]]
address = "10.1.2.4:3306"
username = "categraf"
password = "XXXXXXXX"
interval_times = 8

这个例子里，第一个实例，每 7s 执行一次，第二个实例，每 8s 执行一次。

标签问题

所有监控数据都要附加的标签，配置在 conf/config.toml 的 [global.labels] 中，比如：

[global.labels]
env = "prod"
region = "shanghai"

如果只想给部分实例附加标签，就在各个 instances 下面，比如：

interval = 1
[[instances]]
address = "10.1.2.3:3306"
username = "categraf"
password = "XXXXXXXX"
interval_times = 7
[instances.labels]
instance = "a"
env = "prod"

[[instances]]
address = "10.1.2.4:3306"
username = "categraf"
password = "XXXXXXXX"
interval_times = 8
[instances.labels]
instance = "b"
env = "test"

或者换个写法：

interval = 1
[[instances]]
address = "10.1.2.3:3306"
username = "categraf"
password = "XXXXXXXX"
interval_times = 7
labels = { instance="a", env="prod"}

[[instances]]
address = "10.1.2.4:3306"
username = "categraf"
password = "XXXXXXXX"
interval_times = 8
labels = { instance="b", env="test"}

两种写法在 toml 格式的配置文件中作用相同。

配置文件合并问题

每个插件都有一个目录，有时方便管理，想把插件配置拆成多个文件，也是可以的。Categraf 的处理逻辑是：把插件目录下的所有 toml 文件，按照文件名字排序，拼接成一个大的 toml 文件来处理。

注意，interval 配置是在所有 instances 前面的，所以要拆成多个配置文件的话，只在第一个 toml 文件中配置 interval 即可。其他配置文件的 interval 即便配置了也不生效。所谓的第一个 toml 文件，是把所有 toml 文件按照文件名的字符序排序，取第一个。