All-in-one 的监控数据采集器 Categraf 正式开源

秦晓辉@快猫星云 2026-02-04 00:00:00

简介

Categraf 是一个开源的 all-in-one 的监控数据采集器，由快猫星云开源和维护。

下载安装和使用请参考此处

Categraf 的代码托管在 GitHub

Categraf 的定位类似于 Telegraf、Grafana-agent、Datadog-agent，期望使用一个统一的采集器对所有常见监控对象提供开箱即用的监控数据采集能力，涵盖指标和日志，遵循 OpenTelemetry 标准，兼容 Prometheus 生态，并简化维护成本。

特点

代码开源，遵循 OpenTelemetry 标准，超过 100 万次下载，广受信赖；
性能优异，日志采集相比 filebeat 性能提升 25%；
插件机制，可扩展性强，100 多种插件，插件内置了仪表盘模板、监控策略模板，开箱即用；

对比

Categraf 和 Telegraf、Prometheus exporters、Grafana-agent、Datadog-agent 等的区别与联系

Telegraf 是 InfluxDB 生态的默认采集器，因为 InfluxDB 是支持字符串数据的，所以 Telegraf 采集的很多 field 是字符串类型，另外 InfluxDB 的设计，允许 labels 是非稳态结构，比如 result_code 标签，有时其 value 是 0，有时其 value 是 1，在 Influxdb 中都可以接受。但是上面两点，在类似 Prometheus 的时序库中，处理起来就很麻烦，且非常容易引入高基数问题；
Prometheus 生态有各种现成的 exporters，但是其设计逻辑都是一种监控对象一个 exporter，甚至于一个实例对应一个 exporter，导致在生产环境可能会部署特别多的 exporter 进程，管理成本很高，不易维护；
Grafana-agent 则 import 了大量 exporters 的代码，好处是复用程度高，与 Prometheus 生态兼容，但是在import 代码的过程中没有裁剪，没有优化，没有最佳实践；对于一些中间件，仍然存在一个 grafana-agent 对应着一个目标实例的现象，管理起来很不方便；
Datadog-agent 确实是集大成者，采集插件很丰富，质量高，但是大量代码是 Python 编写的，导致在目标机器上部署依赖复杂，发布包也比较大，有不少历史包袱，而且生态上是自成一派，和社区相对割裂；

所以，Categraf 确实又是一个轮子：

支持 remote_write 写入协议，支持将数据写入 Promethues、M3DB、VictoriaMetrics、InfluxDB 等目标时序数据库；
指标数据只采集数值，不采集字符串，标签维持稳态结构；
采用 all-in-one 的设计，所有的采集工作用一个 agent 搞定，涵盖指标和日志（traces 数据的采集推荐使用 OTEL SDK + OTEL Collector）；
使用 Go 语言编写，静态编译依赖少，容易分发，易于安装；
尽可能落地最佳实践，不需要采集的数据无需采集，针对可能会对时序库造成高基数的问题在采集侧做出处理；
常用的采集器，不但提供采集能力，还要整理出监控大盘和告警规则，用户可以直接导入使用，开箱即用；
支持服务发现、relabel 等机制，支持日志采集时脱敏、多行日志识别等能力；
开源运作，由快猫星云技术团队提供支持，持续迭代，希望更多的公司、更多人研发人员参与共建，做成国内最开放、最好用的采集器；

下载安装和使用

请参考此处

插件说明

采集插件的代码，在代码的 inputs 目录，每个插件一个独立的目录，目录下包含采集代码、以及相关的监控大盘 JSON 文件（如有）和告警规则 JSON 文件（如有），Linux 相关的大盘和告警规则文件统一放到了 inputs/system 目录下（没有分散在 cpu、mem、disk 等采集器目录），方便使用。
插件的配置文件，放在conf目录，以input.打头，如conf/input.xxxx。每个配置文件都有详尽的注释，如果整不明白，就直接去看 inputs 目录下的对应采集器的代码，Go 的代码非常易读，比如某个配置不知道是做什么的，去采集器代码里搜索相关配置项，很容易就可以找到答案。
插件采集的指标默认都会添加一个前缀，比如 input.redis 采集的指标会以redis_ 开头, input.mysql 采集的指标会以mysql_开头。部分插件也支持自定义前缀，像 input.prometheus 和 input.exec 插件。可以通过以下命令观察指标。

如何贡献新的插件，请参考此处。

主配置说明

Categraf 启动时可以通过 -configs 参数指定配置目录，如果不指定，会默认读取工作目录下的 conf。

conf 目录结构如下：

config.toml # 主配置文件
logs.toml # logs-agent 配置文件
prometheus.toml # prometheus agent 配置文件
traces.yaml # trace-agent 配置
conf/input./.toml # 各个插件的配置文件

这里我们先介绍主配置文件和一些通用配置项。

主配置config.toml说明

[global]
# 启动的时候是否在stdout中打印配置内容
print_configs = false

# 机器名，作为本机的唯一标识，会为时序数据自动附加一个 agent_hostname=$hostname 的标签
# hostname 配置如果为空，自动取本机的机器名
# hostname 配置如果不为空，就使用用户配置的内容作为hostname
# 用户配置的hostname字符串中，可以包含变量，目前支持两个变量，
# $hostname 和 $ip，如果字符串中出现这两个变量，就会自动替换
# $hostname 自动替换为本机机器名，$ip 自动替换为本机IP
# 建议大家使用 --test 做一下测试，看看输出的内容是否符合预期
# 这里配置的内容，在--test模式下，会显示为 agent_hostname=xxx 的标签
hostname = ""


# 是否忽略主机名的标签，如果设置为true，时序数据中就不会自动附加agent_hostname=$hostname 的标签
omit_hostname = false

# 时序数据的时间戳使用ms还是s，默认是ms，是因为remote write协议使用ms作为时间戳的单位
precision = "ms"

# 全局采集频率，15秒采集一次
interval = 15

# 全局附加标签，一行一个，这些写的标签会自动附到时序数据上
# [global.labels]
# region = "shanghai"
# env = "localhost"

[log]
# 默认的log输出，到标准输出(stdout) 
# 如果指定为文件, 则写入到指定的文件中
file_name = "stdout"

# options below will not be work when file_name is stdout or stderr
# 如果是写入文件，最大写入大小，单位是MB
max_size = 100
# max_age is the maximum number of days to retain old log files based on the timestamp encoded in their filename.
# 保留多少天的日志文件
max_age = 1
# max_backups is the maximum number of old log files to retain.
# 保留多少个日志文件
max_backups = 1
# local_time determines if the time used for formatting the timestamps in backup files is the computer's local time.
# 是否使用本地时间
local_time = true
# Compress determines if the rotated log files should be compressed using gzip.
# 是否将老文件压缩（gzip格式)
compress = false

# 发给后端的时序数据，会先被扔到 categraf 内存队列里，每个采集插件一个队列
# chan_size 定义了队列最大长度
# batch 是每次从队列中取多少条，发送给后端backend
[writer_opt]
# default: 2000
batch = 2000
# channel(as queue) size
chan_size = 10000

# 后端backend配置，在toml中 [[]] 表示数组，所以可以配置多个writer
# 每个writer可以有不同的url，不同的basic auth信息
[[writers]]
# 注意端口号
# v5版本端口是19000
# v6+版本端口是17000
url = "http://127.0.0.1:17000/prometheus/v1/write"

# Basic auth username
basic_auth_user = ""

# Basic auth password
basic_auth_pass = ""

# timeout settings, unit: ms
timeout = 5000
dial_timeout = 2500
max_idle_conns_per_host = 100

# 是否开启push gateway
[http]
enable = false
address = ":9100"
print_access = false
run_mode = "release"

# 是否启用告警自愈agent
[ibex]
enable = false
## ibex flush interval
interval = "1000ms"
## n9e ibex server rpc address
servers = ["127.0.0.1:20090"]
## temp script dir
meta_dir = "./meta"

# 心跳上报（附带资源信息,对象列表中使用），适用于夜莺v6+
# 如果是v5版本，这里不需要保留
[heartbeat]
enable = true

# 如果心跳携带参数 gid=<group_id> 可以实现自动归属于某个业务组效果
# report os version cpu.util mem.util metadata
url = "http://127.0.0.1:17000/v1/n9e/heartbeat"

# interval, unit: s
interval = 10

# Basic auth username
basic_auth_user = ""

# Basic auth password
basic_auth_pass = ""

## Optional headers
# headers = ["X-From", "categraf", "X-Xyz", "abc"]

# timeout settings, unit: ms
timeout = 5000
dial_timeout = 2500
max_idle_conns_per_host = 100


# embeded prometheus agent mode
[prometheus]
# 是否启用 prometheus agent mode 功能
enable = false

# 可直接使用 prometheus 的 scrape yaml 文件，来描述抓取任务
scrape_config_file = "/path/to/in_cluster_scrape.yaml"

## log level, debug warn info error
log_level = "info"

## wal file storage path ,default ./data-agent
# wal_storage_path = "/path/to/storage"
## wal reserve time duration, default value is 2 hour
# wal_min_duration = 2

对于每个采集器的配置，不在这里一一赘述，只讲一些相对通用的配置项。

interval

每个插件的配置中，一开始通常都是 interval 配置，表示采集频率，如果这个配置注释掉了，就会复用 config.toml 中的采集频率，这个配置如果配置成数字，单位就是秒，如果配置成字符串，就要给出单位，比如：

interval = 60
interval = "60s"
interval = "1m"

上面三种写法，都表示采集频率是1分钟，如果是使用字符串，可以使用的单位有：

秒：s
分钟：m
小时：h

注意：每个插件也只支持一个interval 配置, 如果插件目录中的 toml 文件拆分成了多个，每个文件又包含一个 interval 配置，这个时候以第一个加载的文件内的 interval 为准(默认是字典序第一个文件)。所以一般建议是不配置插件(input)级别的 interval (你很熟悉这个特性除外)，推荐直接配置 interval_times 这个配置项。

interval_times

instances 下面如果有 interval_times 配置项，则采集频率计算如下：interval = global.interval * interval_times，即以 interval 的倍数来表示计算频率。

比如针对 ping 监控，有些目标地址采集频率是 15 秒，有些可能想采集的别太频繁，设置为 30 秒，那就可以把 interval 配置成15，把不需要频繁采集的那些 instances 的interval_times 配置成 2。

或者：把interval配置成5，需要15秒采集一次的那些 instances 的 interval_times 配置成 3，需要30秒采集一次的那些 instances 的 interval_times 配置成 6

instances

很多采集插件的配置中，都有 instances 配置段，用 [[]] 包住，说明是数组，即，可以出现多个 [[instances]] 配置段，比如 ping 监控的采集插件，想对 4 个 IP 做 ping 探测，可以按照下面的方式来配置：

[[instances]]
targets = [
    "www.baidu.com",
    "127.0.0.1",
    "10.4.5.6",
    "10.4.5.7"
]

也可以下面这样子配置：

[[instances]]
targets = [
    "www.baidu.com",
    "127.0.0.1"
]

[[instances]]
targets = [
    "10.4.5.6",
    "10.4.5.7"
]

instances.labels

instances 下面的 labels 和 config.toml 中的 global.labels 的作用类似，只是生效范围不同，都是为时序数据附加标签，instances 下面的 labels 是附到对应的实例上，global.labels 是附到所有时序数据上。

监控大盘和告警规则

Categraf 不止是希望提供尽量多的采集插件，也希望在提供插件的时候同时提供监控大盘和告警规则，导入夜莺即可使用，大家可以去插件列表下的各个目录找一下，通常 alerts.json 表示告警规则，dashboard.json 表示大盘配置。

我们的期望

国内的监控圈子，缺少这样一个大一统的方案，我们希望抛砖引玉，把框架搭建起来，大家一起贡献采集插件，慢慢的生态就起来了，功在当代利在千秋！目前已经有不少公司和个人开发者参与进来了，希望有更多同道参与进来，咱们一起加油！