FastDFS Prometheus Exporter 监控部署指南:容量、性能与健康指标全解析
FastDFS Prometheus Exporter 监控部署指南:容量、性能与健康指标全解析
FastDFS 是典型的高容量分布式文件系统,生产环境中跟踪每个 group 与 storage 节点的磁盘余量、TPS、同步延迟和心跳状态,是保障集群稳定运行的基础。本指南基于仓库 monitoring/prometheus_exporter 提供的官方 Prometheus exporter(fdfs_exporter),完整讲解它的指标体系、编译安装、配置参数、命令行用法,以及与 Prometheus 和 Grafana 的集成方式。读完本文,你将能够独立部署一套覆盖存储容量、读写流量、连接数、同步状态与磁盘 I/O 的 FastDFS 监控方案,并看懂每个指标在源码中的采集逻辑与含义。
一、Exporter 能监控什么:六类核心指标
fdfs_exporter 是一个以独立 HTTP 服务方式运行的 Prometheus exporter,通过 FastDFS 客户端库与 tracker 通信,聚合集群状态后以 Prometheus 文本格式暴露指标。官方 README 将其能力归纳为六类:
- 存储容量与使用情况(Storage capacity and usage):每个 group 和每个 storage 节点的总空间、剩余空间、预留空间与可用空间;
- 上传/下载速率(Upload/download rates):操作次数与传输字节数;
- 连接数(Connection counts):当前连接数与最大连接数(累计分配数);
- 错误率(Error rates):失败操作数,可由"总操作数减去成功操作数"推导得出;
- 同步状态与延迟(Sync status and delays):同步字节数与心跳延迟;
- 磁盘 I/O 统计(Disk I/O statistics):上传、下载、删除、追加、修改五种操作各自的总量与成功量;
- 网络吞吐(Network throughput):上传与下载字节数。
二、采集原理:一次请求背后的调用链
从源码 fdfs_exporter.c 可以看到,每次收到 GET /metrics 请求后,collect_metrics() 按固定顺序完成三类数据采集:
- Tracker 集群状态:调用
tracker_cluster_stat()(声明于 client/tracker_client.h,实现在 client/tracker_client.c),获取每个 tracker 的 leader 状态、激活状态及连接统计; - Group 列表与统计:调用
tracker_list_groups()获取集群全部 group 及总空间、可用空间、预留空间、trunk 空闲空间、storage 节点数与可读/可写节点数; - 每个 group 的 storage 明细:对每个 group 调用
tracker_list_servers()获取该组内每台 storage 节点的容量、各操作计数、连接数、心跳时间与同步进度,再计算组内last_source_update最大值作为同步基准,导出同步延迟。
采集到的所有指标统一以 fastdfs_ 为前缀(源码中 METRIC_PREFIX "fastdfs_"),并按层级区分为三类命名空间:fastdfs_tracker_*、fastdfs_group_*、fastdfs_storage_*。采集完成后,exporter 将 Tracker 连接放回连接池(conn_pool_disconnect_server),并在信号(SIGINT/SIGTERM)触发时调用 fdfs_client_destroy() 优雅退出。
需要说明的是:exporter 本身只聚合与转发数据,各 storage 的统计计数(total_upload_count、success_upload_count、last_source_update 等)由 storage 心跳上报、tracker 维护(参见 tracker/tracker_mem.c 与 tracker/tracker_service.c 中的 long2buff/buff2long 编解码),因此所有指标反映的是 tracker 视角下的集群状态快照。
三、前置条件与编译安装
官方要求的环境依赖如下:
- gcc >= 4.7.0(编译环境)
- libfastcommon(如
/usr/lib64/libfastcommon.so) - libserverframe(如
/usr/lib64/libserverframe.so) - FastDFS 客户端库(如
/usr/lib64/libfdfsclient.so)
构建只需在 monitoring/prometheus_exporter 目录执行:
make
从 Makefile.in 可以看到,编译时通过 -I../../client -I../../common -I../../tracker 引用仓库内的客户端与公共头文件,链接 -lfdfsclient -lfastcommon -lserverframe,产物为单一可执行文件 fdfs_exporter。安装到指定前缀(TARGET_PREFIX)下的 bin 目录可执行 make install。若直接复用仓库源码,也可以跳过安装,就地运行生成的 ./fdfs_exporter。
四、配置文件详解
exporter 支持通过 INI 风格的配置文件(默认示例见 exporter.conf)或命令行参数两种方式配置。配置文件各小节说明如下。
全局配置段(无小节名)
# 本机绑定地址,留空表示绑定本机所有地址
bind_addr =
# 监听端口,默认 9898
port = 9898
# FastDFS 客户端配置文件路径
fdfs_client_cfg = /etc/fdfs/client.conf
# 是否以守护进程方式运行,默认 false
daemon = true
各参数的源码处理逻辑(见 load_from_config_file()):
bind_addr:留空时绑定所有网卡地址,启动日志打印Listening on port 9898;设置如127.0.0.1时仅监听本机回环,防止公网直接抓取;port:合法范围 1~65535,越界会报invalid port number并拒绝启动(默认值DEFAULT_PORT 9898);fdfs_client_cfg:不能为空,exporter 启动时调用fdfs_client_init()读取该文件完成客户端初始化;daemon:为true时调用daemon_init(false)转入后台运行。
认证小节 [auth]
[auth]
# 认证方式:none(无认证)或 basic(HTTP Basic 认证),默认 none,留空视为无认证
method = none
# HTTP Basic 认证用户名,method 为 basic 时不能为空
username = test
# HTTP Basic 认证密码,method 为 basic 时不能为空
password = hello1234
源码实现要点:
method仅接受none与basic两个值,其余值报unkown auth method并退出;- 当
method = basic时,username与password均不能为空,且二者拼接后长度不能超过 128 字节(超出报EOVERFLOW); - 程序在启动时将
username:password做 Base64 编码缓存起来,每个请求在check_authorization()中解析 HTTP 头的Authorization:字段并做精确比对,不匹配则返回401 Unauthorized; - 注意:该认证只做凭据比对,本身不依赖 FastDFS 用户体系,密码以明文形式存在于配置文件中,生产环境应设置合理的文件权限(如仅 root 可读)。
FastDFS 客户端配置文件
fdfs_client_cfg 指向的是标准 FastDFS 客户端配置,仓库示例见 conf/client.conf。exporter 对它的依赖包括:
tracker_server(通过#include tracker_servers.conf引入):指定 tracker 地址列表;connect_timeout/network_timeout:与 tracker 通信的超时控制;base_path:客户端日志等运行文件的存放目录;use_connection_pool:是否启用连接池,开启后connection_pool_max_idle_time控制空闲连接回收。
部署时请把该文件中的 tracker 地址替换为实际集群地址,并确保运行 exporter 的主机能够访问 tracker 端口。
五、命令行参数与运行方式
查看全部参数:
./fdfs_exporter -h
源码 usage() 与 longopts 中定义的参数如下:
| 短参数 | 长参数 | 含义 | 默认值 |
|---|---|---|---|
-B |
--bind_addr |
绑定本机 IP,如 127.0.0.1 |
绑定所有地址 |
-c |
--config_file |
指定 exporter 配置文件 | 无(不读取) |
-f |
--fdfs_client_cfg |
指定 FastDFS 客户端配置 | FDFS_CLIENT_DEFAULT_CONFIG_FILENAME |
-d |
--daemon |
以守护进程方式运行 | 前台运行 |
-P |
--port |
指定监听端口 | 9898 |
-h |
--help |
显示帮助 | — |
典型启动方式:
# 使用命令行参数,指定客户端配置与端口
./fdfs_exporter -f /etc/fdfs/client.conf -P 9898
# 使用配置文件(含认证、daemon 等全部设置)
./fdfs_exporter -c exporter.conf
参数优先级说明:源码先扫描 -c 指定的配置文件并加载其中设置,随后再次解析命令行参数,命令行中出现的 -B/-d/-f/-P 会覆盖配置文件对应值。启动成功后,默认监听 9898 端口,指标端点固定为:
http://localhost:9898/metrics
只有 GET /metrics 请求会被处理,其余路径返回 404 Not Found。验证方式:
curl http://localhost:9898/metrics
六、指标清单:完整字段与标签
以下指标均来自 fdfs_exporter.c 中 export_* 系列函数的实际输出,类型统一为 Prometheus gauge。
Tracker 级指标(fastdfs_tracker_*,标签 host)
| 指标名 | 含义 |
|---|---|
fastdfs_tracker_is_leader |
该 tracker 是否为 leader(1/0) |
fastdfs_tracker_is_active |
该 tracker 是否激活(1/0) |
fastdfs_tracker_connections_alloc |
累计分配的连接数 |
fastdfs_tracker_connections_current |
当前连接数 |
fastdfs_tracker_connections_max |
最大连接数 |
Group 级指标(fastdfs_group_*,标签 group)
| 指标名 | 含义 |
|---|---|
fastdfs_group_total_mb |
组内磁盘总空间(MB) |
fastdfs_group_free_mb |
组内剩余空间(MB) |
fastdfs_group_reserved_mb |
组内预留空间(MB) |
fastdfs_group_available_mb |
可用空间(free_mb - reserved_mb,为负时按 0 处理) |
fastdfs_group_trunk_free_mb |
trunk 文件空闲空间(仅当组启用 trunk 时输出) |
fastdfs_group_storage_count |
组内 storage 节点总数 |
fastdfs_group_readable_server_count |
组内可读节点数 |
fastdfs_group_writable_server_count |
组内可写节点数 |
Storage 级指标(fastdfs_storage_*,标签 group, storage_id, ip, status)
容量与空间:
| 指标名 | 含义 |
|---|---|
fastdfs_storage_total_mb / fastdfs_storage_free_mb / fastdfs_storage_reserved_mb |
节点总/剩余/预留空间(MB) |
fastdfs_storage_available_mb |
节点可用空间(free_mb - reserved_mb,负值截为 0) |
操作计数(每种操作均提供 _total 与 _success,二者之差即为失败数,对应 README 所述"错误率由总数与成功数计算"):
| 指标名 | 含义 |
|---|---|
fastdfs_storage_upload_total / upload_success |
上传操作总数 / 成功数 |
fastdfs_storage_download_total / download_success |
下载操作总数 / 成功数 |
fastdfs_storage_delete_total / delete_success |
删除操作总数 / 成功数 |
fastdfs_storage_append_total / append_success |
追加写操作总数 / 成功数 |
fastdfs_storage_modify_total / modify_success |
修改操作总数 / 成功数 |
fastdfs_storage_upload_bytes_total |
累计上传字节数 |
fastdfs_storage_download_bytes_total |
累计下载字节数 |
连接与状态:
| 指标名 | 含义 |
|---|---|
fastdfs_storage_connections_alloc / connections_current / connections_max |
连接分配 / 当前 / 最大数 |
fastdfs_storage_last_heartbeat |
最近一次心跳时间戳 |
fastdfs_storage_heartbeat_delay_seconds |
距最近心跳的秒数(now - last_heart_beat_time) |
fastdfs_storage_last_synced_timestamp |
最近一次同步时间戳 |
fastdfs_storage_synced_delay_seconds |
同步延迟秒数(组内最大 last_source_update 与自身 last_synced_timestamp 之差;未同步过为 -1,异常场景下被截为 0) |
fastdfs_storage_sync_in_bytes_total / sync_out_bytes_total |
累计同步入 / 同步出字节数 |
status 标签对应 storage 节点的在线状态码,与 FastDFS 约定一致(如 FDFS_STORAGE_STATUS_ONLINE 等,可参考 common/fdfs_define.h),配合 heartbeat_delay_seconds 即可判断节点是否失联。所有标签在源码中一次拼接,形如:
fastdfs_storage_total_mb{group="group1",storage_id="...",ip="10.0.0.1",status="1"} 102400
七、Prometheus 抓取配置
在 Prometheus 的 prometheus.yml 中新增抓取任务,官方示例:
scrape_configs:
- job_name: 'fastdfs'
static_configs:
- targets: ['localhost:9898']
scrape_interval: 30s
要点:
scrape_interval: 30s已足够:exporter 每次抓取都会实时向 tracker 发起一次完整查询,过短的间隔会额外增加 tracker 压力;若想更快发现节点故障,可缩短至 10~15s,代价是 tracker 查询频率升高;- 若在 exporter 配置中启用了
method = basic,则抓取配置需补充 Basic Auth 凭据:
scrape_configs:
- job_name: 'fastdfs'
static_configs:
- targets: ['localhost:9898']
scrape_interval: 30s
basic_auth:
username: test
password: hello1234
八、Grafana 仪表盘
仓库提供了开箱即用的仪表盘 JSON:grafana_dashboard.json,在 Grafana 中通过 Import 上传该文件即可生成 "FastDFS Monitoring Dashboard"(数据源选择 Prometheus)。该仪表盘包含 8 个面板,其中核心查询表达式可直接复用到自建面板或告警规则中:
| 面板 | PromQL 表达式 |
|---|---|
| 总存储空间 Total Storage Space | sum(fastdfs_storage_total_mb) |
| 剩余空间占比 Free Space % | sum(fastdfs_storage_free_mb) / sum(fastdfs_storage_total_mb) * 100 |
| 总节点数 Total Storage Servers | sum(fastdfs_group_storage_count) |
| 活跃节点数 Active Storage Servers | sum(fastdfs_group_active_count) |
| 每秒操作数 TPS | rate(fastdfs_storage_upload_total[5m])、rate(fastdfs_storage_download_total[5m]) |
| 吞吐 Traffic (Bytes/sec) | rate(fastdfs_storage_upload_bytes_total[5m])、rate(fastdfs_storage_download_bytes_total[5m]) |
| 磁盘使用率 Disk Usage % | (fastdfs_storage_total_mb - fastdfs_storage_free_mb) / fastdfs_storage_total_mb * 100 |
| 心跳延迟 Heartbeat Delay (seconds) | fastdfs_storage_heartbeat_delay_seconds |
其中磁盘使用率与心跳延迟面板已内置阈值配色(使用率 90% 变红、心跳延迟 60s 黄色、120s 红色),可作为告警阈值的起点。
九、常见告警规则示例
基于上述指标可以快速建立生产告警:
groups:
- name: fastdfs
rules:
# 节点剩余空间低于 10%
- alert: FastDFSDiskAlmostFull
expr: (sum by (storage_id) (fastdfs_storage_free_mb) /
sum by (storage_id) (fastdfs_storage_total_mb)) * 100 < 10
for: 5m
labels: { severity: warning }
# 节点心跳超过 120 秒视为疑似失联
- alert: FastDFSStorageHeartbeatTimeout
expr: fastdfs_storage_heartbeat_delay_seconds > 120
for: 2m
labels: { severity: critical }
# 同步延迟超过 300 秒
- alert: FastDFSSyncDelayHigh
expr: fastdfs_storage_synced_delay_seconds > 300
for: 5m
labels: { severity: warning }
十、部署注意事项
- 端口与安全:exporter 监听
9898端口,自身仅提供只读指标;若集群内网可信,可将bind_addr留空,否则建议绑定内网地址或启用 Basic Auth 后再对 Prometheus 暴露; - 认证模式选择:
method = basic时,需同时确保username与password非空,且抓取端(Prometheus)配置一致的凭据; - 依赖与版本:exporter 依赖 libfastcommon、libserverframe、libfdfsclient 三个共享库,且直接使用 FastDFS 客户端 API(
tracker_list_groups、tracker_list_servers、tracker_cluster_stat),运行时版本应与集群 tracker 兼容;README 列出的前置条件(gcc >= 4.7.0)针对编译环境,生产机通常只需三个共享库; - 与客户端 API 的关系:exporter 并未自己实现 tracker 协议细节,而是复用 client/tracker_client.c 提供的标准查询接口,因此它对集群数据结构的理解与
fdfs_monitor等官方工具保持一致,指标口径可信; - 构建与系统集成:仓库还提供了 systemd 单元(systemd/fdfs_trackerd.service 等)可作为部署参考模式;若要让 exporter 开机自启,可参照编写对应的 systemd 服务单元,用
-c指定配置文件并以daemon = true或前台方式运行。
十一、许可证
该 exporter 及其配套文件遵循 GPL V3 许可(见 monitoring/prometheus_exporter 目录与源码文件头注释),在分发或二次开发前请留意许可证条款。
结语
fdfs_exporter 以约千行的轻量 C 实现,将 FastDFS 集群的容量、吞吐、连接、心跳与同步状态完整映射为 Prometheus 指标,配合仓库附带的 grafana_dashboard.json 即可在数分钟内建立起一套可视化监控。理解其"tracker 查询 + 三层指标命名空间 + 总量/成功量对比"的设计后,无论是扩展自研面板、编写告警还是二次开发,都能从 fdfs_exporter.c 和 exporter.conf 找到直接依据。