Categraf 主配置说明

讲解 Categraf 的主配置文件 config.toml，包括采集频率、机器名、全局标签、写入端、心跳和 Prometheus Agent 等通用配置。

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]
# Categraf 标准日志的输出位置和文件轮转配置，不包含日志级别配置
# 默认输出到标准输出(stdout)，也可配置 stderr
# 如果指定为文件, 则写入到指定的文件中
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"

## Prometheus Agent 的日志级别，支持 debug、info、warn、error，默认 info
# 与插件实例的 log_level 分别配置；当前版本对标准日志的影响见下文
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

这里先介绍一些相对通用的配置项。

日志输出与日志级别

Categraf 的日志配置分为输出位置、组件日志级别和调试开关。配置文件中的字段名是 log_level。

配置项	配置位置	作用
`file_name`、`max_size` 等	`config.toml` 的 `[log]`	配置 Categraf 标准日志的输出位置和文件轮转，不提供 `level` 或 `log_level` 字段
`log_level`	`config.toml` 的 `[prometheus]`	设置内置 Prometheus Agent 的 logger 级别
`log_level`	支持该字段的插件配置文件中的 `[[instances]]`	设置对应实例的 exporter logger 级别，取值和默认行为由插件决定
`--debug`	启动命令	开启代码中由调试开关控制的输出，默认关闭
`--debug-level`	启动命令	设置部分插件使用的数字调试参数，默认 `0`；具体生效条件见下文

命令行调试参数 `--debug-level`

./categraf -h 中的 -debug-level 接收整数，默认值为 0。单横线和双横线写法都可以，例如 -debug-level 5、--debug-level 5。它用于开启部分插件的额外调试信息，不对应 debug、info、warn、error 等日志级别，也没有统一的逐级含义；是否生效取决于插件代码中的判断条件。

当前代码中的使用场景如下：

组件	生效条件	输出内容
SNMP 插件	`--debug-level` 大于 `4`，例如 `5`	开启底层 GoSNMP 库的调试日志，直接输出到 stdout；这一条件不要求同时指定 `--debug`
node_exporter 的 buddyinfo collector	同时指定 `--debug`，且 `--debug-level` 大于 `2`，例如 `3`	通过标准日志输出读取到的 buddyinfo 数据；需要已启用该 collector

例如，在已有有效 SNMP 采集配置时，可以这样排查采集过程：

./categraf --configs conf --inputs snmp --debug --debug-level 5

这里 --debug 开启插件自身的调试输出，--debug-level 5 额外开启 GoSNMP 库的调试日志。两者是独立参数，设置 --debug-level 不会自动开启 --debug，也不会修改 Prometheus Agent 或插件实例 logger 的 log_level。

Prometheus Agent 的日志级别

在主配置文件 config.toml 中配置：

[prometheus]
enable = true
scrape_config_file = "/path/to/in_cluster_scrape.yaml"
log_level = "info"

支持 debug、info、warn、error，分别输出所选级别及更高级别的日志。例如 info 输出 INFO、WARN、ERROR，过滤 DEBUG。省略或设置为空时使用 info。修改主配置中的日志级别后，需要重启 Categraf。

排查 Prometheus Agent 问题时，也可以使用：

./categraf --configs conf --debug --inputs prometheus-agent

同时指定 --debug 且 --inputs 包含 prometheus-agent 时，Prometheus Agent 使用 debug，优先于 [prometheus].log_level；单独指定 --debug 不会覆盖这个配置项。--inputs 还会筛选采集插件，排查结束后应恢复正常启动参数。

插件实例的日志级别

部分插件内置了独立的 exporter logger。例如，MongoDB 使用 logrus，Kafka 和 Apache 使用 go-kit/log。它们的 log_level 配置在各自的 [[instances]] 中，与 [prometheus].log_level 分别生效，也不会自动继承它的值。

以 conf/input.mongodb/mongodb.toml 为例：

[[instances]]
mongodb_uri = "mongodb://127.0.0.1:27017"
log_level = "debug"

插件	支持的 `log_level`	默认行为
MongoDB	`panic`、`fatal`、`error`、`warn`（或 `warning`）、`info`、`debug`、`trace`	省略时使用 `info`；非法值会导致实例初始化失败
Kafka	`debug`、`info`、`warn`、`error`	随附配置文件设置为 `error`；省略或填写其他值时不过滤 exporter 日志
Apache	`debug`、`info`、`warn`、`error`	省略或填写其他值时使用 `info`

这些字段控制传入 exporter 的实例 logger，不会统一修改 logrus 的全局 logger，也不能控制插件中所有通过标准 log 打印的消息。--debug 同样不会自动把这些 exporter logger 的级别改成 debug。上述 MongoDB、Kafka 的实例 logger 默认输出到 stderr，Apache 输出到 stdout，输出位置不由主配置的 [log].file_name 控制。

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 是附到所有时序数据上。

关于 TLS 的配置

在很多插件中，都有 tls 相关的配置项，表示是否使用 TLS 来连接采集对象。

  use_tls = false
  tls_min_version = "1.2"
  tls_ca = "/etc/categraf/ca.pem"
  tls_cert = "/etc/categraf/cert.pem"
  tls_key = "/etc/categraf/key.pem"
  ## Use TLS but skip chain & host verification
  insecure_skip_verify = true