FastDFS Prometheus Exporter 监控部署指南:容量、性能与健康指标全解析

原创2026-09-24 23:41:442,299 阅读
文章标签:后端分布式文件系统存储数据同步高可用负载均衡

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() 按固定顺序完成三类数据采集:

  1. Tracker 集群状态:调用 tracker_cluster_stat()(声明于 client/tracker_client.h,实现在 client/tracker_client.c),获取每个 tracker 的 leader 状态、激活状态及连接统计;
  2. Group 列表与统计:调用 tracker_list_groups() 获取集群全部 group 及总空间、可用空间、预留空间、trunk 空闲空间、storage 节点数与可读/可写节点数;
  3. 每个 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 找到直接依据。

登录后查看全文
fastdfs