Zabbix 插件

介绍监控数据采集器 Categraf 的 Zabbix 插件与配置

简介

Zabbix 插件用于将 Zabbix 中的监控数据转换为Prometheus格式的指标，进而转发给后端存储。该插件支持两种数据获取方式：从Zabbix文件导出功能读取历史数据文件，或者通过HTTP接收Zabbix实时流式数据。企业版 Categraf v0.4.10开始支持此功能，开源版不支持此插件。

Zabbix 导出数据方式

Zabbix支持两种导出数据的方式，插件均可支持处理：

导出数据到外部系统从Zabbix 7.0开始支持，通过HTTP将数据流式传输到Categraf 如何配置
导出数据到文件从Zabbix 4.0开始支持，将数据保存到NDJSON格式文件中供Categraf读取如何配置

采集配置

[[instances]]
## 同一个instance下，只能endpoint 和 data_dir 二选一
## endpoint 是categraf启动的监听地址，用于接收zabbix发送的数据
# endpoint=":9109"
## data_dir 是zabbix导出的数据目录，必须让categraf有可读权限
data_dir="/home/flashcat/zabbix/data"
## 给转换后的指标添加一个自定义前缀
#prefix="zabbix"

endpoint 是categraf的启动的监听地址，用于接收zabbix推送的数据
data_dir 是zabbix导出的数据目录，必须让categraf有可读权限

这两项配置是互斥的，只能二选一

配置zabbix api连接

插件需要通过Zabbix API获取item详细信息以正确解析监控数据。需要提供能够访问item.get接口的Zabbix api token。

企业版v0.4.10/v0.4.11 版本仅支持用户名密码方式获取item数据, 最佳实践更推荐使用api token方式,请使用v0.4.12及以上版本。创建api token请参照文档

[instances.zabbix]
## zabbix的访问地址 可以带具体路径，也可以只是IP端口
server="http://192.168.10.222"
## zabbix的版本，目前支持6.x和7.x, 其他版本未验证
version="7.2"
## zabbix的api token
api_token="xxxx"
##  zabbix的指标名（item.name字段） 是否作为label 
##  如果设置为true , 会添加一个标签 description=${item.name}
#name_as_tag=true

指标映射配置

插件使用 items 配置来定义如何解析和转换Zabbix指标。可以在 input 或 instances 级别定义 items 配置。

[[items]]
## item.key 以什么格式接收数据 必选项
## 参考item types说明文档 https://www.zabbix.com/documentation/7.2/en/manual/config/items/itemtypes/zabbix_agent
key = "system.cpu.util[<cpu>,<type>,<mode>,<logical or physical>]"
## 指定模板中的参数默认值，如果数据中不提供这些参数，则使用默认值
default_value = {cpu = "all", type = "user", mode = "avg1", logical_or_physical = "logical"}
## 定义这个指标的名字(可选)，如不指定则自动从key名和参数生成，最终指标名字中的 . 会替换为 _ 
## 通常都不需要指定这个值
## 自动拼接可以参考自定义指标转换示例部分
metric_name = "system_cpu_utilization"

自定义指标转换示例

[[items]]
key = "zabbix[stats,<ip>,<port>,queue,<from>,<to>]"
default_value = {ip = "127.0.0.1", port = "10051", from = "6s"}
# 自动生成的指标名为zabbix_stats_queue,  中括号之前的内容+常量参数拼接
# metric_name = ""


[[items]]
key = "system.cpu.load[<cpu>,<mode>]"
default_value = {cpu = "all", mode = "avg1"}
## 自动生成的指标名为system_cpu_load
# metric_name = ""


[[items]]
key = "vm.memory.size[<mode>]"
default_value = {mode = "pused"}

# 自动生成的指标名为vm_memory_size
# metric_name = ""

工作原理

数据文件监控模式

插件会定期扫描指定目录下的.ndjson文件
当发现新文件或文件内容变化时，读取新增内容并解析
文件处理遵循增量读取原则，记录上次读取位置
默认情况下，10分钟无变化的文件会被视为不活跃

HTTP接收器模式

插件启动HTTP服务器监听指定端口
接收Zabbix发送的实时数据
接口路径为${endpoint}/v1/zabbix/history

指标转换逻辑

根据Item的key和参数解析原始数据
提取宿主机、组、标签等信息作为Prometheus标签
数字类型的值直接转换为指标值
对于JSON格式的文本值，会尝试提取嵌套的数值数据

一份完整配置

  # input级别的Item配置
  [[items]]
  key = "system.cpu.util[<cpu>,<type>,<mode>]"
  default_value = {cpu = "all", type = "user", mode = "avg1"}

  # 实例配置
  [[instances]]
  # 如果使用HTTP接收模式
  endpoint = ":9109"
  # prefix = "zabbix"

  [instances.zabbix]
  server = "http://zabbix-server.example.com"
  version = "7.2"
  api_token="xxxx"
  # name_as_tag = true

  # instances级别的Item配置，会覆盖input相同key配置
  [[instances.items]]
  key = "vfs.fs.size[<fs>,<mode>]"
  default_value = {}

Zabbix 配置指南

导出数据到文件

zabbix_server.conf中配置

ExportDir=/path/to/export/directory
ExportFileSize=1G  # 可选：设置最大文件大小
ExportType=history # 导出类型

使用环境变量

ZBX_EXPORTDIR=/path/to/export/directory/
ZBX_EXPORTFILESIZE=1G
ZBX_EXPORTTYPE=history

导出数据到http receiver

zabbix_server.conf中配置

StartConnectors=5

使用环境变量

ZBX_STARTCONNECTORS=5

在Zabbix前端配置Connector (Administration → General → Connectors)

数据类型：选择"Item values"
URL：指向Categraf的endpoint+"/v1/history"，如http://categraf:9109/v1/history
设置标签过滤器（可选）

参考文档

故障排查

查看日志是否有API调用错误
- Fatal error: Allowed memory size of xxxx bytes exhausted 修改 /etc/php-fpm.d/zabbix.conf php_admin_value[memory_limit] = xxxM
确认Zabbix版本
确认Zabbix导出功能已正确配置
确保Zabbix API连接配置正确
检查API Token权限是否足够
检查文件路径或HTTP endpoint配置
验证文件权限或网络连接