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

总结一下社区常见的问题，供大家参考。不过在描述具体问题之前，请先了解 Categraf 的核心职能：
采集监控指标
在即时查询里可以看到机器各个指标的历史趋势图，就是 Categraf 采集的监控指标。比如：

如果这个页面查不到机器的历史监控数据，说明采集、上报、存储链路出了问题。
上报机器元信息
机器列表里的机器，会呈现一些字段，比如更新时间、时间偏移、内存、CPU 等字段，都是通过 Categraf 上报的元信息拿到的。

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

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

hostname 配置

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

1. # add label(agent_hostname) to series
2. # "" -> auto detect hostname
3. # "xx" -> use specified string xx
4. # "$hostname" -> auto detect hostname
5. # "$ip" -> auto detect ip
6. # "$hostname-$ip" -> auto detect hostname and ip to replace the vars
7. hostname = ""

复制代码

上面的注释其实也说得很清楚了，我这里也再啰嗦一下。
hostname 字段用户配置成啥，就以啥作为机器标识。所以，不同机器一定要配置为不同的字符串。
但是每个机器都要配置一个不同的字符串，有点费劲，能否自动设置为本机的机器名？可以的，这个字段如果留空，就会自动获取本机的机器名。
有些公司机器名可能会重复，想要自动设置为本机 IP，也可以，那就配置为：

1. hostname = "$ip"

复制代码

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

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

复制代码

hostname 的信息会体现为指标里的 agent_hostname 标签，如上，我的本机 IP 自动探测为 10.99.1.107。
有时想从环境变量里获取，也可以，也是使用 $ 符号引用环境变量的名称即可，比如：

1. [root@iZ2ze4oi71k3qgdxwsyn07Z categraf-v0.4.20-linux-amd64]# export HOST=hello007
2. [root@iZ2ze4oi71k3qgdxwsyn07Z categraf-v0.4.20-linux-amd64]# grep HOST conf/config.toml
3. hostname = "$HOST"
4. [root@iZ2ze4oi71k3qgdxwsyn07Z categraf-v0.4.20-linux-amd64]# ./categraf --test --inputs mem 2>/dev/null| grep mem_
5. 1762167642 19:00:42 mem_active agent_hostname=hello007 1265184768
6. 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 配置

配置段样例如下：

1. [[writers]]
2. url = "http://nightingale:17000/prometheus/v1/write"
3. basic_auth_user = ""
4. basic_auth_pass = ""
5. timeout = 5000
6. dial_timeout = 2500
7. 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 地址，比如：

1. [[writers]]
2. url = "http://ip1:17000/prometheus/v1/write"
3. basic_auth_user = ""
4. basic_auth_pass = ""
5. timeout = 5000
6. dial_timeout = 2500
7. max_idle_conns_per_host = 100
8. [[writers]]
9. url = "http://ip2:17000/prometheus/v1/write"
10. basic_auth_user = ""
11. basic_auth_pass = ""
12. timeout = 5000
13. dial_timeout = 2500
14. 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 是个数组，比如：

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

复制代码

多个监控目标的问题

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

1. [[instances]]
2. address = "127.0.0.1:3306"
3. username = "categraf"
4. password = "XXXXXXXX"

复制代码

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

1. [[instances]]
2. address = "10.1.2.3:3306"
3. username = "categraf"
4. password = "XXXXXXXX"
5. [[instances]]
6. address = "10.1.2.4:3306"
7. username = "categraf"
8. password = "XXXXXXXX"

复制代码

采集频率问题

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

1. interval = 15
2. [[instances]]
3. address = "10.1.2.3:3306"
4. username = "categraf"
5. password = "XXXXXXXX"
6. interval_times = 1
7. [[instances]]
8. address = "10.1.2.4:3306"
9. username = "categraf"
10. password = "XXXXXXXX"
11. interval_times = 2

复制代码

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

1. interval * interval_times

复制代码

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

1. interval = 1
2. [[instances]]
3. address = "10.1.2.3:3306"
4. username = "categraf"
5. password = "XXXXXXXX"
6. interval_times = 7
7. [[instances]]
8. address = "10.1.2.4:3306"
9. username = "categraf"
10. password = "XXXXXXXX"
11. interval_times = 8

复制代码

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

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

1. [global.labels]
2. env = "prod"
3. region = "shanghai"

复制代码

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

1. interval = 1
2. [[instances]]
3. address = "10.1.2.3:3306"
4. username = "categraf"
5. password = "XXXXXXXX"
6. interval_times = 7
7. [instances.labels]
8. instance = "a"
9. env = "prod"
11. [[instances]]
12. address = "10.1.2.4:3306"
13. username = "categraf"
14. password = "XXXXXXXX"
15. interval_times = 8
16. [instances.labels]
17. instance = "b"
18. env = "test"

复制代码

或者换个写法：

1. interval = 1
2. [[instances]]
3. address = "10.1.2.3:3306"
4. username = "categraf"
5. password = "XXXXXXXX"
6. interval_times = 7
7. labels = { instance="a", env="prod"}
9. [[instances]]
10. address = "10.1.2.4:3306"
11. username = "categraf"
12. password = "XXXXXXXX"
13. interval_times = 8
14. labels = { instance="b", env="test"}

复制代码

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

每个插件都有一个目录，有时方便管理，想把插件配置拆成多个文件，也是可以的。Categraf 的处理逻辑是：把插件目录下的所有 toml 文件，按照文件名字排序，拼接成一个大的 toml 文件来处理。
注意，interval 配置是在所有 instances 前面的，所以要拆成多个配置文件的话，只在第一个 toml 文件中配置 interval 即可。其他配置文件的 interval 即便配置了也不生效。所谓的第一个 toml 文件，是把所有 toml 文件按照文件名的字符序排序，取第一个。

来源：程序园用户自行投稿发布，如果侵权，请联系站长删除
免责声明：如果侵犯了您的权益，请联系站长，我们会及时删除侵权内容，谢谢合作！

喜欢鼓捣这些软件，现在用得少，谢谢分享！

东西不错很实用谢谢分享

这个好，看起来很实用

新版吗？好像是停更了吧。

前排留名，哈哈哈

感谢分享，下载保存了，貌似很强大

很好很强大  我过来先占个楼 待编辑

感谢分享，学习下。

不错，里面软件多更新就更好了

这个有用。

用心讨论，共获提升！

谢谢分享，试用一下

收藏一下   不知道什么时候能用到

很好很强大  我过来先占个楼 待编辑

感谢发布原创作品，程序园因你更精彩

前排留名，哈哈哈

谢谢分享，试用一下

yyds。多谢分享

yyds。多谢分享