夜莺监控系统使用手册

本文档将详细介绍夜莺监控系统的使用方法，帮助更好地接入主机监控服务、配置数据采集插件、导入仪表盘以及管理告警。

1. 接入多台主机监控服务 🚀

要在被监控主机上接入夜莺监控系统，只需安装 categraf 并在其配置文件 conf/config.toml 中配置监控主机的夜莺系统地址。这样，本地 categraf 抓取的数据便会自动上传到监控主机的夜莺系统。

以下是 categraf 配置文件中的关键部分：

Ini, TOML

[[writers]]
url = "http://监控主机:17000/prometheus/v1/write"

[heartbeat]
enable = true
# report os version cpu.util mem.util metadata
url = "http://监控主机IP:17000/v1/n9e/heartbeat"

成功接入后，可以在夜莺系统的“基础设施-机器列表”中查看到被监控主机。

2. 数据接入：categraf 插件使用 🔌

进入 categraf 的 conf 目录，您会看到许多配置文件，主要包括主配置文件 config.toml、日志代理配置文件 logs.toml、Prometheus 代理配置文件 prometheus.toml、追踪代理配置 traces.yaml，以及各个插件的配置文件 input.*/*.toml。大部分监控服务需要手动配置才能开启数据采集。

主配置 config.toml 说明

以下是 config.toml 中一些重要的全局配置项：

• print_configs：启动时是否在标准输出中打印配置内容，默认为 false。

• hostname：作为本机的唯一标识，会自动为时序数据附加 agent_hostname=$hostname 标签。如果留空，则自动获取本机机器名；如果配置不为空，则使用用户配置的内容作为 hostname。支持变量 $hostname（自动替换为本机机器名）和 $ip（自动替换为本机 IP）。建议使用 --test 进行测试。

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

• precision：时序数据的时间戳单位，默认为 ms（毫秒），因为 remote write 协议使用毫秒作为时间戳单位。

• interval：全局采集频率，默认为 15 秒采集一次。

• [global.labels]：全局附加标签，每行一个，这些标签会自动附加到时序数据上。

Ini, TOML

[global]
print_configs = false
hostname = ""
omit_hostname = false
precision = "ms"
interval = 15
# [global.labels]
# region = "shanghai"
# env = "localhost"

日志配置 [log]

• file_name：默认日志输出到标准输出 (stdout)。如果指定为文件，则写入到指定文件中。

• max_size：如果写入文件，最大写入大小，单位为 MB，默认为 100。

• max_age：保留多少天的日志文件，默认为 1 天 1。

• max_backups：保留多少个日志文件，默认为 1 个 2。

• local_time：是否使用本地时间格式化备份文件中的时间戳，默认为 true 3。

• compress：是否将旧文件压缩（gzip 格式），默认为 false 4。

Ini, TOML

[log]
file_name = "stdout"
max_size = 100
max_age = 1
max_backups = 1
local_time = true
compress = false

写入器优化 [writer_opt]

发给后端（backend）的时序数据会先被放入 categraf 内存队列中，每个采集插件一个队列。

• chan_size：定义队列最大长度，默认为 10000。

• batch：每次从队列中取多少条数据发送给后端，默认为 2000。

Ini, TOML

[writer_opt]
batch = 2000
chan_size = 10000

后端配置 [[writers]]

toml 中 [[]] 表示数组，因此可以配置多个 writer。每个 writer 可以有不同的 url 和 basic auth 信息。

Ini, TOML

[[writers]]
url = "http://监控机夜莺IP:17000/prometheus/v1/write" # 注意端口号：v5版本是19000，v6+版本是17000
basic_auth_user = ""
basic_auth_pass = ""
timeout = 5000
dial_timeout = 2500
max_idle_conns_per_host = 100

HTTP 配置 [http]

• enable：是否开启 push gateway，默认为 false。

• address：监听地址，默认为 :9100。

• print_access：是否打印访问日志，默认为 false。

• run_mode：运行模式，默认为 release。

Ini, TOML

[http]
enable = false
address = ":9100"
print_access = false
run_mode = "release"

告警自愈代理 [ibex]

• enable：是否启用告警自愈代理，默认为 false。

• interval：ibex flush 间隔，默认为 1000ms。

• servers：夜莺 ibex server rpc 地址，默认为 ["127.0.0.1:20090"]。

• meta_dir：临时脚本目录，默认为 ./meta。

Ini, TOML

[ibex]
enable = false
interval = "1000ms"
servers = ["127.00.1:20090"]
meta_dir = "./meta"

心跳上报 [heartbeat]

心跳上报（附带资源信息，用于对象列表），适用于夜莺 v6+ 版本。如果心跳携带参数 gid=<group_id> 可以实现自动归属于某个业务组的效果。

Ini, TOML

[heartbeat]
enable = true
url = "http://监控机夜莺IP:17000/v1/n9e/heartbeat"
interval = 10 # unit: s
basic_auth_user = "" [cite: 6]
basic_auth_pass = "" [cite: 6]
timeout = 5000 [cite: 6]
dial_timeout = 2500 [cite: 6]
max_idle_conns_per_host = 100 [cite: 6]

内嵌 Prometheus 代理模式 [prometheus]

• enable：是否启用 prometheus agent mode 功能，默认为 false。

• scrape_config_file：可直接使用 Prometheus 的 scrape yaml 文件来描述抓取任务。

• log_level：日志级别，可选 debug、warn、info、error，默认为 info。

• wal_storage_path：wal 文件存储路径，默认为 ./data-agent。

• wal_min_duration：wal 保留时长，默认为 2 小时。

Ini, TOML

[prometheus]
enable = false
scrape_config_file = "/path/to/in_cluster_scrape.yaml"
log_level = "info"
# wal_storage_path = "/path/to/storage"
# wal_min_duration = 2

TLS 配置（可选）🔒

许多插件中都包含 tls 相关配置项，表示是否使用 TLS 连接采集对象。

• use_tls：为 true 时，表示使用 tls 连接到采集对象。

• tls_min_version：支持的最小 tls 版本，可选值有 1.0、1.1、1.2、1.3。SSLv3 不支持。

• tls_ca、tls_cert、tls_key：分别是 ca 证书、客户端证书、客户端私钥。

• insecure_skip_verify：设置为 true 时，表示使用 TLS 但跳过链和主机验证。如果证书是自签证书，想要避免 X509: certificate signed by unknown authority 错误，可以设置此项。注意：目前的设计中，这两个参数是共同起作用的，单独设置 insecure_skip_verify = true 无法避免该错误 5。

Ini, TOML

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"
insecure_skip_verify = true

3. 采集插件的使用/启动 ⚙️

categraf 拥有大量的服务插件。您可以通过官方文档或 GitHub 文档查看具体插件的使用方法：

• 官方文档：插件综述 - 快猫星云Flashcat

• GitHub 文档：categraf/inputs at main · flashcatcloud/categraf · GitHub

GitHub 中的每个插件都有 README 文件，建议通过 GitHub 进行查阅。此外，也可以在夜莺的“集成中心-模板中心-选中对应的数据源-采集说明”中查看对应数据源的采集方法。

以 MySQL 服务监控为例

以下是 mysql 服务监控的配置示例：

Ini, TOML

[[instances]]
address = "IP:3306"
username = "root"
password = "1234"
labels = { instance="n9e-localhost:3306" }

# # set tls=custom to enable tls
# parameters = "tls=false"

extra_status_metrics = true
extra_innodb_metrics = false
gather_processlist_processes_by_state = false
gather_processlist_processes_by_user = false
gather_schema_size = true
gather_table_size = false
gather_system_table_size = false
gather_slave_status = true

需要注意的是，如果要监控一台主机中的多个 mysql 服务，务必打好标签，例如 labels = { instance="zbx-10.2.6.9:3306" }，否则在监控大盘中会非常混乱。如果是监控不同主机的 mysql 服务，最好使用 IP 地址而不是本地子网或 localhost。

通过上述配置，即可启动插件采集不同主机的 mysql 服务。

思考💡： 被监控机的 categraf 配置文件已经接入了监控机的夜莺系统，理论上插件抓取到的数据都会通过 categraf 上传到监控机的夜莺系统，因此只需要启动被监控机的插件服务即可。至于同一台机器的多个服务如何集成到监控，需要根据具体配置文件（每个都不同）进行调整。

4. 导入/创建仪表盘 📊

夜莺内置了一些仪表盘，但实际使用体验可能不佳，UI 界面也可能不够友好。建议导入 Grafana 的仪表盘来使用。

在夜莺的“仪表盘-监控仪表盘”中选择“导入”，可以前往 Grafana 仪表盘市场 https://grafana.com/grafana/dashboards/ 寻找合适的仪表盘。

5. 告警管理 🚨

夜莺的告警结构以告警规则为中心定义。在告警规则中设置告警媒介，然后在告警接收组中与相应的媒介用户进行匹配。

例如，设定告警规则 A 通过微信和邮件进行告警联系。当告警产生时，系统会在预设的组 G 中匹配微信和邮件。夜莺将不同的告警方式以用户的身份进行划分。

如果要增加告警途径/方式，需要在“人员组织-用户管理”中“添加用户”（重点在于联系方式），添加成功后将其划分到通知组群。这样告警架构就设定好了。

除了邮箱需要 SMTP 服务外，其他通知只需在对应的应用上设定好机器人，产生告警时夜莺便会自动推送。

以飞书为例

1. 首先在飞书群聊中添加群聊机器人（右上角设置 - 添加群聊机器人）。

2. 保存 Webhook 链接。

3. 在夜莺用户管理中“新增”用户，并在联系方式中填写 Webhook 链接，然后将新创建的用户添加到通知团队（如果没有则创建一个）。

4. 新增告警规则（测试），选择一个便于测试的参数。

5. 告警接收组选择告警的团队。保存。

这样就设置好了，稍等片刻即可看到机器人上报的告警通知。