OneUptime Ceph Agent 部署指南基于 OpenTelemetry Collector 的 Ceph 集群监控【免费下载链接】oneuptimeComplete open-source monitoring and observability platform.项目地址: https://gitcode.com/GitHub_Trending/on/oneuptime导读本文围绕 OneUptime 的 Ceph Agent 展开它本质上是一个预配置的 OpenTelemetry Collector负责抓取 Ceph mgrprometheus模块暴露的指标集群健康、mon 法定人数、OSD、pool 与 placement group并在每个指标上打上集群身份标识后通过 OTLP 转发至 OneUptime。读完本文你将掌握从启用 mgr prometheus 模块、快速安装、环境变量配置到验证、可选项日志采集、额外抓取目标、systemd 托管、升级卸载与故障诊断的完整实战链路。一、OneUptime Ceph Agent 是什么OneUptime Ceph Agent 是 OneUptime 提供的一个预配置的 OpenTelemetry Collector 容器用于监控 Ceph 集群。它的核心设计目标有三个抓取 Ceph mgrprometheus模块从每一个mgr 守护进程抓取指标——健康状态、mon quorum、OSD、pool 和 placement groupPG保证故障转移下的指标连续性由于只有 active mgr 才返回指标Agent 会同时抓取全部 mgr 端点使 active-mgr 切换后指标持续流动无需任何配置变更打上集群身份标识通过ceph.cluster.name资源属性将每个指标标记为某个具体集群OneUptime 据此自动注册集群并路由数据。在 OneUptime 的数据链路中Agent 只负责采集与上报真正的告警与可视化由 Ceph Monitor 完成——Ceph Monitor 文档Ceph Monitor说明了如何基于这些指标配置监控与告警。两者配合的完整闭环是Agent 采集 → OneUptime 按ceph.cluster.name自动注册集群 → Ceph Monitor 基于指标评估告警。从源码角度可以进一步印证这一点服务端 CephClusterService.ts 中明确注明 A Ceph cluster is keyed by theceph.cluster.nameOTel resource attributeCeph 集群以ceph.cluster.nameOTel 资源属性为键TelemetryEntity.ts 中ceph.cluster实体仅依赖ceph.cluster.name完成发现与注册。这正是文档中反复强调保持CEPH_CLUSTER_NAME稳定、不要随意修改的根本原因。二、前置条件在安装 Agent 之前需要满足以下条件条件说明Docker Engine 20.10需安装 Docker Compose v2 插件运行在任意能访问 Ceph mgr 守护进程端口 9283的机器上Ceph mgrprometheus模块已启用启用方法见下文OneUptime 遥测摄取令牌在Project Settings → Telemetry APM → Ingestion Keys中创建并复制启用 mgr Prometheus 模块在 Ceph 集群上执行ceph mgr module enable prometheus启用后每个mgr 守护进程都会在端口9283的/metrics路径上提供 Prometheus 指标。这里有一个关键行为需要理解只有 active mgr 会返回指标——standby mgr 返回空响应若将mgr/prometheus/standby_behaviour设置为error则返回 HTTP 错误。这正是 Agent 必须抓取所有 mgr 端点、而不是只抓 active 的原因当 active mgr 故障转移时指标仍能持续流动无需任何配置变更。要列出集群中的 mgr 守护进程ceph mgr stat # 查看 active mgr ceph orch ps --daemon-type mgr # 列出全部 mgrcephadm 集群三、快速开始使用安装脚本最简单的方式是使用 CephAgent 目录下提供的 install.sh 安装脚本curl -sSL https://raw.githubusercontent.com/OneUptime/oneuptime/master/CephAgent/install.sh -o install.sh bash install.sh脚本会依次做以下事情检查前置条件确认docker命令存在、Docker daemon 可访问、docker composev2 插件可用对应 install.sh 中的三段检查任一不满足即报错退出交互式收集配置提示输入 OneUptime URL、遥测摄取令牌、集群名称、mgr 端点列表。如果环境变量已经设置则直接复用而不重复询问见 install.sh自动补齐方括号CEPH_MGR_ENDPOINTS若以裸逗号分隔列表形式输入脚本会自动用方括号包裹install.sh确保 Collector 能将其解析为抓取目标列表下载并安装安装到/opt/oneuptime-ceph-agent下载docker-compose.yml与otel-collector-config.yaml生成权限为 600 的.env文件启动 Agent在安装目录下执行docker compose up -d。脚本还会在结束时打印常用运维命令提示查看状态、日志、停止、重启便于后续操作。四、备选方案手动 Docker Compose 部署如果不想使用安装脚本可以从 CephAgent 目录获取两个文件——docker-compose.yml 与 otel-collector-config.yaml——放入同一文件夹并在旁边创建.env文件ONEUPTIME_URLYOUR_ONEUPTIME_URL ONEUPTIME_TELEMETRY_INGESTION_KEYYOUR_TELEMETRY_INGESTION_TOKEN CEPH_CLUSTER_NAMEmy-ceph-cluster CEPH_MGR_ENDPOINTS[ceph-mon-1:9283,ceph-mon-2:9283,ceph-mon-3:9283]⚠️务必列出全部 mgr 守护进程active 与 standby用逗号分隔并用方括号包裹——方括号会让 Collector 将值解析为抓取目标列表缺少方括号则整个字符串会被当成单个无效目标。启动docker compose up -d就这么简单。Agent 连接成功后你的集群会自动出现在 OneUptime 仪表盘的Ceph部分。docker-compose.yml 关键点从 docker-compose.yml 可以看到使用官方镜像otel/opentelemetry-collector-contrib:latest容器名固定为oneuptime-ceph-agent将本地otel-collector-config.yaml以只读方式挂载到/etc/otelcol-contrib/config.yaml通过环境变量注入四项配置其中CEPH_CLUSTER_NAME带默认值ceph${CEPH_CLUSTER_NAME:-ceph}restart: unless-stopped保证容器异常退出后自动重启日志采用 json-file 驱动限制为单文件 10MB、最多 3 个文件避免日志无限增长。五、环境变量详解变量必填说明ONEUPTIME_URL是OneUptime 实例地址例如https://oneuptime.com或自托管地址ONEUPTIME_TELEMETRY_INGESTION_KEY是从Project Settings → Telemetry APM → Ingestion Keys获取的遥测摄取令牌CEPH_CLUSTER_NAME是在 OneUptime 中显示的集群标识会以ceph.cluster.name资源属性形式打在每条指标上。保持稳定——事后更改会注册为第二个集群而非重命名。默认值为cephCEPH_MGR_ENDPOINTS是全部 mgr 守护进程的逗号分隔host:port列表用方括号包裹例如[ceph-mon-1:9283,ceph-mon-2:9283,ceph-mon-3:9283]。安装脚本会自动为你补上方括号六、Agent 的抓取原理otel-collector-config.yaml 中的prometheusreceiver 揭示了核心抓取配置1. 全部 mgr、30 秒间隔mgr prometheus 模块会为每次抓取缓存mgr/prometheus/scrape_interval默认 15 秒时间内的结果。抓取间隔绝不能低于 15 秒——那样只会重复读取缓存数据。30 秒是随附配置的生产默认值otel-collector-config.yaml。2.honor_labels: trueCeph 导出的标签ceph_daemon、pool_id、各守护进程的 instance 标签会被原样保留。若关闭该选项instance标签会在每次抓取目标切换时被重写并随 active mgr 的变化而翻转从而破坏时序series的连续性otel-collector-config.yaml。3. 资源属性处理器resource processor这是数据归属的关键。配置中的resource处理器会执行以下操作otel-collector-config.yamlupsertceph.cluster.name把${env:CEPH_CLUSTER_NAME}打入每条指标——OneUptime 服务端正是依据该属性自动注册 Ceph 集群见上文源码佐证可选的ceph.cluster.fsid默认注释掉如需可用ceph fsid获取后启用删除service.name与service.instance.idPrometheus receiver 会按照 Prometheus→OTLP 兼容规范为每个批次合成service.name等于抓取任务名oneuptime-ceph与service.instance.id。OneUptime 首先按service.name路由批次若不删除数据会被路由到一个幽灵的 oneuptime-ceph Service 而不会进入由ceph.cluster.name发现的 Ceph 集群同时也会破坏按集群设置的保留策略。配置注释中明确警告不要移除这两条 delete 操作。4. 导出与管道OTLP HTTP exporter 指向${env:ONEUPTIME_URL}/otlp并通过x-oneuptime-token请求头携带摄取令牌otel-collector-config.yaml。指标管道依次经过memory_limiter256 MiB 上限、64 MiB 尖峰、resource打身份标签、batch10 秒超时、单批 1024 条后导出。七、验证安装检查 Agent 是否运行docker compose ps查看 Collector 日志docker logs -f oneuptime-ceph-agent在日志中寻找如下字样Everything is ready. Begin running and processing data.大约一分钟内集群应出现在 OneUptime 仪表盘中并开始有指标流动。八、采集了哪些指标Agent 会原样上报 mgr prometheus 模块导出的全部指标。OneUptime 的 Ceph 仪表盘、指标目录和告警模板主要基于以下系列构建集群健康Cluster Health指标说明ceph_health_status整体健康状态0 OK1 WARN2 ERRceph_health_detail每个活跃健康检查一个系列带name/severity标签Quincy 及以后版本驱动健康检查告警模板与仪表盘的why下钻ceph_healthcheck_slow_opsSLOW_OPS 健康检查报告的慢操作数ceph_daemon_health_metrics按守护进程的健康指标以type标签区分ceph_mon_quorum_statusmon 是否在法定人数内按ceph_daemon区分ceph_mon_metadatamon 元数据ceph_cluster_total_bytes/ceph_cluster_total_used_bytes集群总容量 / 已用容量字节OSD指标说明ceph_osd_up/ceph_osd_inOSD 是否 up / 是否在数据分布中按ceph_daemon如osd.3区分ceph_osd_apply_latency_ms/ceph_osd_commit_latency_msOSD 应用延迟 / 提交延迟毫秒ceph_osd_stat_bytes/ceph_osd_stat_bytes_used每个 OSD 底层设备的原始容量 / 已用字节ceph_osd_numpg每个 OSD 承载的 placement group 数ceph_osd_metadataOSD 元数据hostname、device_class、version值恒为 1求和可统计 OSD 数量Pool指标说明ceph_pool_stored/ceph_pool_max_avail池中用户数据字节 / 在给定副本或 EC 配置下仍可写入的字节ceph_pool_objects池中对象数ceph_pool_rd/ceph_pool_wr池累计读 / 写操作数ceph_pool_rd_bytes/ceph_pool_wr_bytes池累计读 / 写字节数ceph_pool_metadata池元数据——唯一将pool_id映射到池名称的系列注意pool 的数据系列只携带pool_id标签池名称只存在于ceph_pool_metadata上。过滤和分组应基于pool_id需要显示名称时再关联元数据系列。Placement GroupPG指标说明ceph_pg_total/ceph_pg_active/ceph_pg_clean每池 PG 总数 / active 状态数 / clean 状态数均按pool_id区分ceph_pg_degraded/ceph_pg_undersized每池 degraded / undersized 状态 PG 数ceph_num_objects_degraded副本数低于配置的对象数ceph_num_objects_misplaced未落在 CRUSH 预期 OSD 上的对象数九、可选的额外抓取目标mgr 模块覆盖了集群级的健康与容量。若需要更深的可见性可在otel-collector-config.yaml的scrape_configs下增加更多 jobceph-exporterReef 18.2——cephadm 会在每个集群主机上部署ceph-exporter守护进程在端口9926提供逐守护进程的性能计数器。需要为每个主机添加一个目标node_exporter——Ceph 主机 OS 级指标CPU、内存、磁盘、网络的标准搭档默认端口9100。两者都会继承随附resource处理器打上的ceph.cluster.name资源属性因此在 OneUptime 中会归属于同一个集群。十、可选采集 Ceph 集群日志Agent 可以追踪/var/log/ceph/ceph.log并上报至 OneUptime为 Ceph 仪表盘的Cluster Log页面提供数据。该功能默认关闭因为要求 Agent 运行在持有集群日志的主机上默认是 mon 主机。启用步骤取消注释otel-collector-config.yaml中的filelogreceiver 与logspipeline取消注释docker-compose.yml中的/var/log/ceph卷挂载即- /var/log/ceph:/var/log/ceph:ro重启docker compose up -d。相关实现细节otel-collector-config.yamlfilelogreceiver 的include指向/var/log/ceph/ceph.logstart_at: end表示从文件末尾开始追踪这样 Agent 重启不会重复上报整个文件日志行原样发送OneUptime 在读取时解析 ceph.log 格式时间戳、守护进程、INF/WRN/ERR 级别、消息并由resource处理器打上ceph.cluster.name使日志归属于对应集群。十一、作为 systemd 服务运行对于服务器场景可以将 Agent 托管为 systemd 服务。仓库中已提供 oneuptime-ceph-agent.servicesudo cp systemd/oneuptime-ceph-agent.service /etc/systemd/system/ sudo systemctl daemon-reload sudo systemctl enable --now oneuptime-ceph-agent该 unit 假设 Agent 安装在/opt/oneuptime-ceph-agent安装脚本的默认路径。从 unit 内容可以看到其设计要点Afternetwork-online.target docker.service且Wantsnetwork-online.target确保网络与 Docker 就绪后再启动ExecStartPre先执行docker compose pull拉取最新镜像ExecStart以--remove-orphans启动Restarton-failure配合RestartSec30失败后 30 秒自动重试TimeoutStartSec120、TimeoutStopSec30控制启动/停止超时。十二、升级与卸载升级 Agentcd /opt/oneuptime-ceph-agent docker compose pull docker compose up -d卸载 Agentcd /opt/oneuptime-ceph-agent docker compose down十三、自托管 OneUptime如果自托管 OneUptime将ONEUPTIME_URL设置为自己的实例ONEUPTIME_URLhttps://your-oneuptime-host.example.com若实例仅支持 HTTP则使用http://并附带相应端口。十四、故障排查首选先运行诊断脚本Agent 随附一个 doctor 脚本 troubleshoot.sh会检查整条链路。获取并运行curl -sSL https://raw.githubusercontent.com/OneUptime/oneuptime/master/CephAgent/troubleshoot.sh -o troubleshoot.sh bash troubleshoot.sh # 若安装在非 /opt/oneuptime-ceph-agent 目录加 -d dir脚本覆盖的检查项对应 troubleshoot.sh 中的 8 个 section运行时Docker 是否可用、daemon 是否可达、容器是否存在且处于 running 状态--skip-egress可跳过出网测试--curl-image可指定探测镜像mgr 端点检查CEPH_MGR_ENDPOINTS是否有方括号、是否只配置了一个端点会警告故障转移后指标将静默停止、逐个探测每个端点是否为 active mgr通过是否返回ceph_health_status判断并确认配置中保留honor_labels: true集群名称盖章确认CEPH_CLUSTER_NAME非空且配置中包含ceph.cluster.name资源处理器摄取令牌形态检查令牌是否为空、是否含空白字符、是否为合法 UUID——任何异常都会导致 OneUptime 静默丢弃数据Collector 自指标从容器网络命名空间内抓取127.0.0.1:8888/metrics统计otelcol_receiver_accepted_metric_points、otelcol_exporter_sent_metric_points与otelcol_exporter_send_failed_出网与权威令牌校验见下方说明近期 Collector 错误扫描最近 500 行日志中的错误关键字VERDICT 结论按优先级给出最可能的根因与修复建议。脚本最后会输出VERDICT部分点名最可能的根因。它之所以能给出决定性结论是因为它处理了 OneUptime 一个刻意设计的行为troubleshoot.sh 的注释中详细说明OneUptime 的 OTLP 端点在令牌无效时故意返回静默的200防止配置错误的 Collector 对服务器发起重试洪泛这意味着即使每个数据点都被丢弃Collector 日志看起来也一切正常。脚本通过在 Agent 的网络命名空间内调用GET url/otlp/v1/validate获得真实的200有效/401无效判定旧版服务器无此端点时回退到POST /fluentd/v1/logs该路径走相同的鉴权但非/otlp路径坏令牌会返回400 Invalid service token。注意由于 Collector 镜像是 distroless无 shell、无 curl脚本的网络探测会以兄弟容器方式运行一个 curl 镜像并共享 Agent 容器的网络命名空间--network container:oneuptime-ceph-agent走的是与 Collector 完全相同的路径DNS、代理、防火墙、TLS。集群未出现在 OneUptime 中检查 Collector 日志docker logs oneuptime-ceph-agent——导出时报401说明令牌无效connection refused 说明ONEUPTIME_URL错误验证 mgr 是否提供指标curl http://ACTIVE_MGR_HOST:9283/metrics | head应输出ceph_*指标行。若没有启用模块ceph mgr module enable prometheus确认CEPH_MGR_ENDPOINTS用方括号包裹——缺少方括号时Collector 会把整个逗号分隔字符串当成单个无效目标。mgr 故障转移后指标停止很可能只抓取了之前的 active mgr。在CEPH_MGR_ENDPOINTS中列出每一个mgr 守护进程——抓取 standby mgr 开销很小且返回的是空响应。Collector 日志中出现 standby mgr 的抓取错误如果集群将mgr/prometheus/standby_behaviour设置为errorstandby 会以 HTTP 500 应答这是预期行为。active mgr 的抓取仍然成功因此这些只是噪音将行为切回default即可消除。指标归属到错误的集群OneUptime 依据ceph.cluster.name自动注册 Ceph 集群该属性来自CEPH_CLUSTER_NAME环境变量。在首批遥测数据之后修改它会创建第二个集群条目而不是重命名现有集群旧集群将保持 Disconnected 状态。十五、后续进阶配置Ceph Monitor对健康状态、OSD 可用性、PG 状态、容量、守护进程崩溃、时钟偏移、慢操作等发起告警详见 Ceph Monitor 文档。该文档还提供了 23 个预置告警模板Cluster Health Error、OSD Down、Inactive Placement Groups、Cluster Near Full 等以及指标查询、聚合、过滤、分组与滚动时间窗口的完整配置说明若以 Ceph 作为 Proxmox VE 的存储可将此 Agent 与 OneUptime Proxmox Agent 文档 配对使用需要单主机 OS 级视图时参考 Host OpenTelemetry Collector 文档。关键文件索引安装脚本CephAgent/install.shCompose 编排CephAgent/docker-compose.ymlCollector 配置CephAgent/otel-collector-config.yaml诊断脚本CephAgent/troubleshoot.shsystemd 单元CephAgent/systemd/oneuptime-ceph-agent.serviceCeph Monitor 文档App/FeatureSet/Docs/Content/en/monitor/ceph-monitor.md服务端集群注册依据Common/Server/Services/CephClusterService.ts、Common/Server/Utils/Telemetry/TelemetryEntity.ts【免费下载链接】oneuptimeComplete open-source monitoring and observability platform.项目地址: https://gitcode.com/GitHub_Trending/on/oneuptime创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考