Nightingale 集成 Doris 监控：基于 categraf prometheus 插件采集 FE/BE 指标实战指南

Doris 的 Frontend（FE）与 Backend（BE）进程均内置 Prometheus 协议端点，通过 /metrics 暴露运行时监控数据。本文以 integrations/Doris/markdown/README.md 为核心，讲解如何借助 categraf 的 prometheus 插件，将 Doris 集群的 FE（默认 8030 端口）与 BE（默认 8040 端口）指标采集进 Nightingale，并结合仓库内置的告警规则与仪表盘完成从采集、展示到告警的完整监控闭环。读完本文你将掌握 prometheus.toml 中关键参数（urls、url_label_key、url_label_value、labels）的精确用法，以及 Doris 专属指标与告警表达式的实战语义。

采集原理：Doris 原生暴露 Prometheus 协议

Doris 的所有进程（FE 与 BE）都会暴露 /metrics HTTP 接口，该接口直接输出 Prometheus 文本格式的监控数据。也就是说，Doris 本身就是一台"自带 exporter"的组件，无需额外部署独立的 exporter 进程。

正因为数据已经是 Prometheus 协议，采集侧不需要做任何协议转换，直接使用 categraf 自带的 prometheus 插件（即 input.prometheus）抓取即可。categraf 的 prometheus 插件会定期请求目标 URL 列表，将返回的指标序列解析后上报到 Nightingale 服务端。

采集配置：编辑 prometheus.toml

采集配置位于 categraf 的 conf/input.prometheus/prometheus.toml（categraf 是 Nightingale 官方配套的采集 Agent，该路径是 categraf 自身的配置文件路径）。仓库中为 Doris 准备的完整可复制样例见 integrations/Doris/collect/prometheus/collect_doris_examples.toml，原文档给出的核心配置如下：

# doris_fe
[[instances]]
urls = [
     "http://127.0.0.1:8030/metrics"
]

url_label_key = "instance"
url_label_value = "{{.Host}}"

labels = { group = "fe",job = "doris_cluster01"}

# doris_be
[[instances]]
urls = [
     "http://127.0.0.1:8040/metrics"
]
url_label_key = "instance"
url_label_value = "{{.Host}}"
labels = { group = "be",job = "doris_cluster01"}

这份配置的关键点在于：为 FE 和 BE 各写了一个独立的 [[instances]] 块，因为两者的 /metrics 服务地址不同（FE 默认 8030，BE 默认 8040），且需要打上不同的分组标签以便后续在仪表盘和告警中区分角色。

参数逐项说明

参数	取值示例	作用
urls	["http://127.0.0.1:8030/metrics"]	待抓取的 /metrics 地址列表，可配置多个地址
url_label_key	instance	为每个抓取地址的数据附加一个标签键，用于标识数据来自哪个 scrape url，默认即 instance，不建议改成别的
url_label_value	{{.Host}}	标签值，支持 Go template 语法；为空时取整个 url 字符串，也可通过模板变量只截取一部分
labels	{ group = "fe", job = "doris_cluster01" }	为本次 instance 抓到的所有指标统一附加的静态标签（K/V 形式）

url_label_value 的 Go template 用法

url_label_value 是 categraf prometheus 插件相对原始 telegraf/prometheus 增加的特性（该插件 fork 自 telegraf/prometheus 并做了删减改造）。它用于把"指标来自哪个地址"沉淀为一条标签，常用做法是只取 host 部分：

url_label_value = "{{.Host}}"

例如抓取 http://10.0.0.1:8030/metrics 时，instance 标签的值就是 10.0.0.1:8030。模板中可用的变量由插件解析 URL 后生成，integrations/Prometheus/markdown/README.md 给出了完整的变量集合与生成逻辑：

模板变量	含义
{{.Scheme}}	协议部分，如 http
{{.Host}}	主机与端口，如 127.0.0.1:8030
{{.Hostname}}	仅主机名，不含端口
{{.Port}}	仅端口号
{{.Path}}	URL 路径，如 /metrics
{{.Query}}	查询参数
{{.Fragment}}	fragment 片段

如果需要同时保留协议、主机与路径信息，可以组合书写：

url_label_value = "{{.Scheme}}://{{.Host}}{{.Path}}"

为什么要打 group/job 标签：与内置仪表盘联动

原文档配置中的 labels = { group = "fe", job = "doris_cluster01" } 并非随意添加。打开仓库内置的 Doris 总览仪表盘 integrations/Doris/dashboards/Doris_Overview.json，可以看到其面板查询大量依赖这两个标签：

• 集群选择变量 cluster_name 的定义是 label_values(up, job)，即从采集上来的 up 指标中枚举所有 job 值作为集群下拉选项；
• FE 存活面板使用 up{group="fe"}，BE 存活面板使用 up{group="be"}；
• 变量 fe_instance、be_instance 分别基于 up{group="fe", job="$cluster_name"} 与 up{group="be", job="$cluster_name"} 生成，用于筛选 FE/BE 节点；
• 主 FE 变量 fe_master 通过 node_info{group="fe", job="$cluster_name", type="is_master"} 正则提取 instance 得到。

因此，如果去掉 group 和 job 标签，仪表盘将无法区分 FE 与 BE 角色，集群变量也会为空。job 建议用集群名（如 doris_cluster01），group 用 fe/be 区分角色，并保持与仪表盘约定一致；多集群部署时，只需为每个集群复制一份 [[instances]] 并修改 job 与 urls。

进阶配置：认证、TLS、服务发现与其他选项

prometheus 插件的完整可选项以注释形式列在 integrations/Prometheus/collect/prometheus/prometheus.toml 中，按需启用即可：

# 采集间隔，默认跟随全局 interval
interval = 15

# bearer token 认证（两种方式任选）
bearer_token_string = ""
bearer_token_file = ""

# basic auth 认证
username = ""
password = ""

# 附加请求头
headers = ["X-From", "categraf"]

# 间隔倍数：interval = global.interval * interval_times
interval_times = 1

# 静态标签
labels = {}

# 忽略指标名（支持 glob）
ignore_metrics = [ "go_*" ]

# 忽略标签键（支持 glob）
ignore_label_keys = []

# 单 url 抓取超时
timeout = "3s"

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

插件还支持通过 Consul 做目标地址的服务发现（[instances.consul] 段），管理全部抓取目标；Kubernetes 相关能力已在 fork 时移除，不在此插件内提供。生产环境中，如果 Doris 的 /metrics 端口未暴露在集群外部或开启了认证，可以结合上面的 basic auth / bearer token / TLS 参数完成采集。

配置完成后如何验证

1. 将上述 FE、BE 两个 [[instances]] 块合并写入 categraf 的 conf/input.prometheus/prometheus.toml，重启 categraf 进程；
2. 在目标机器上用 curl http://127.0.0.1:8030/metrics、curl http://127.0.0.1:8040/metrics 确认接口可达且返回 Prometheus 文本；
3. 在 Nightingale 的指标查询页面检索 doris_fe_、doris_be_ 前缀的指标，确认数据已入库；也可直接导入 integrations/Doris/dashboards/Doris_Overview.json 查看总览面板是否渲染出 FE/BE 节点。

配套告警规则：面向 Doris 运行特征

仓库为 Doris 准备了开箱即用的告警规则集 integrations/Doris/alerts/doris_by_categraf.json，共 20+ 条规则（cate 为 prometheus，告警级别 severity 均为 2，默认处于 disabled: 1 未启用状态，导入后按需启用）。规则覆盖了 FE 与 BE 两侧的典型故障场景，按监控对象可分为四组：

BE 资源与线程池积压

规则	PromQL 核心	阈值语义
Doris_BE CPU 使用率	(sum(doris_be_cpu)by(instance)-sum(doris_be_cpu{mode=~"idle|iowait"})by(instance))/sum(doris_be_cpu)by(instance)*100	去除 idle/iowait 后的 CPU 使用率超过 70%
Doris_BE OlapScanner 线程池积压	doris_be_scanner_thread_pool_queue_size	扫描线程池队列 > 0 即告警（已有排队）
Doris_BE batch 线程池队列积压	doris_be_add_batch_task_queue_size	导入批次队列 > 20
Doris_BE 发送数据包线程池积压	doris_be_send_batch_thread_pool_queue_size	节点间数据传输队列 > 0
Doris_BE TCP 包接收错误	increase(doris_be_snmp_tcp_in_errs[1m])	1 分钟内有新增接收错误包

FE 查询与延迟

规则	PromQL 核心	阈值语义
Doris_FE 95/99 百分位查询延迟	doris_fe_query_latency_ms{quantile="0.95"} / {quantile="0.99"}	P95 > 5000ms、P99 > 10000ms
Doris_FE 每秒错误查询数	doris_fe_query_err_rate	每秒错误查询数 > 1
Doris_FE JVM 内存使用率	sum by (ident)(jvm_heap_size_bytes{type="used"}) / sum by (ident)(jvm_heap_size_bytes{type="max"})	JVM 堆使用率 > 85%

FE 事务与元数据

规则	PromQL 核心	阈值语义
Doris_FE 事务执行/publish 耗时 95/99 分位	doris_fe_txn_exec_latency_ms / doris_fe_txn_publish_latency_ms 的 quantile="0.95"/"0.99"	执行与发布阶段 P95 > 5000ms、P99 > 10000ms
Doris_FE 失败/被拒绝/异常事务	increase(doris_fe_txn_counter{type="failed"|"reject"}[5m])、doris_fe_txn_status{type=~"aborted|unknown"}	5 分钟内有失败/被拒绝事务，或存在 aborted/unknown 状态事务
Doris_FE 日志写入延迟 95/99 分位	doris_fe_editlog_write_latency_ms	editlog 写入 P95 > 1000ms、P99 > 2000ms
Doris_FE 元数据镜像/日志相关失败	increase(doris_fe_image_write[1m])、increase(doris_fe_image_clean[1m])、increase(doris_fe_edit_log_clean[1m])	1 分钟内出现镜像生成/清理、日志清理失败计数

规则中附带的排障动作

值得说明的是，每条规则在 annotations.action 中都内置了一份可直接照做的排障动作清单（对应的英文翻译可在 integrations/Doris/i18n/en_US.json 中找到）。例如：

• FE 内存告警：用 jstat -gcutil <pid> 1000 观察 GC 与老年代占用，用 SHOW PROC '/statistic' 查看表/分区/tablet 规模，调大 FE JAVA_OPTS -Xmx 并滚动重启；
• 查询延迟告警：在 FE 上 SHOW PROCESSLIST 定位慢查询，按 fe.audit.log 的 QueryTime 排序找 TOP 慢 SQL，用 EXPLAIN 检查是否命中分区裁剪、前缀索引与 colocate join；
• 事务 publish 慢：查 fe.log 确认是 publish 阶段还是执行阶段慢，用 SHOW PROC '/statistic' 检查不健康副本数，评估导入并发与单批数据量；
• editlog 写入慢：用 iostat -x 1 确认元数据目录磁盘是否打满，检查 FE 元数据目录是否与数据盘混用（建议独占 SSD）。

数据流全链路回顾

从配置到呈现，Doris 监控数据在 Nightingale 体系中的流转路径为：

1. Doris FE/BE 进程通过内置 /metrics 端点持续输出 Prometheus 格式指标（FE 默认 8030、BE 默认 8040）；
2. categraf 的 prometheus 插件按 urls 列表周期抓取，通过 url_label_key/url_label_value 为数据附加来源标签，通过 labels 附加 group/job 静态标签；
3. 指标上报至 Nightingale 服务端，进入时序存储；
4. Doris_Overview.json 仪表盘依据 group/job 标签渲染 FE/BE 节点与集群总览；
5. doris_by_categraf.json 告警规则按阈值持续评估，命中后触发通知并附带内置排障动作。

整个链路无需任何第三方 exporter，仅靠"应用自暴露 Prometheus 协议 + categraf prometheus 插件"即可完成，这也是 Nightingale 集成生态中对自带 /metrics 的组件（如 RabbitMQ、ClickHouse 等）通用的采集范式。