作为一个常年跟分布式执行链路打交道的人我对“监控大屏”这件事态度一直很矛盾做浅了就是接几个图表把数据画出来老板看一眼就不看了做深了又容易陷进具体的组件细节里压根看不到整体。但 Harness 层的 Agent 运行状态可视化不一样它是那种“不做不知道做了才觉得真该早做”的基础工程。这里说的 Harness 层你可以把它理解成任务调度和 Agent 执行之间的“中间管理层”负责统一管理海量 Agent 的生命周期、承接指令下发、收集执行结果。没有这层透明化Agent 到底在干嘛、卡在哪、有没有在空转全凭猜。我在实际经历里最大的体会就是这类监控大屏核心不是那张大屏而是“运行状态可视化的数据模型怎么建立”。所以这篇不是讲三个大屏模板怎么套用而是从 Harness 层的架构边界、指标口径、数据采集链路到前端 WebSocket 推送、状态漂移的排查把整条思路完整还原一遍。如果你正在做类似的基础设施可视化项目或者刚接手 Agent 稳定性治理但觉得无从下手这篇应该能给你省下不少弯路。1. 项目背景与整体设计先把监控边界画清楚1.1 数据分层与 Harness 层到底扮演什么角色任何监控大屏项目第一步绝对不是选图表框架而是先弄清楚你要服务的是哪一层数据。一个常见的分布式任务系统大概可以分成三个层面应用服务层面向用户的功能比如提交任务、查看结果。Harness/调度管理层负责把任务翻译成 Agent 可执行的指令管理 Agent 注册、健康检查、升级、负载分配。它更像是“监工”不直接搬砖但每一块砖运没运到、由谁运的它最清楚。Agent 执行层真正跑在服务器上的底层执行器执行命令、跑模型推理、写文件、上报状态。我们做的 Harness 层监控大屏服务的正是中间这层。当时有同事建议把监控范围扩大到整条业务链路被我们拦住了。如果从页面按钮一路画到服务器 CPU看板必然臃肿最后什么都看不清。既然标题写的是“Harness 层”那最佳口径就是把 Agent 状态、指令分发情况、Agent 集群健康度作为主体上层业务只展示吞吐趋势底层硬件只留几个应急参考指标。1.2 项目真正的目标复现“异常瞬间”而不只是画图还有一个设计层面的问题值得讲清楚监控大屏和报警平台有什么不同报警平台是在出问题时喊你监控大屏则是让你平时就能感知系统正在发生什么。但更核心的一个目标是当某类异常出现能通过大屏快速还原出事那一刻的状态。比如之前有一次 Agent 批量失联当时如果只看日志只能知道一条条超时记录。但大屏上一定要能让我们一眼看出失联是有时间先后顺序的还是同时消失的分布在哪些机器上失联前是不是有过大批指令下发。这种按时间轴回放的 Agent 运行状态可视化才是大屏项目真正值钱的地方。如果做成纯“当前在线数”那种仪表盘就没有这个复现现场的能力了。2. 指标体系建设最容易返工却最没人重视的环节2.1 核心指标到底要选哪些为什么是这些确定了大屏边界后最先要做的是指标清单而不是先画原型。Harness 层最关键的 Agent 运行状态指标我按照自己踩过坑后的经验分成四组生命周期类注册 Agent 数、在线 Agent 数、离线 Agent 数、启动中 Agent 数。用来判断整个集群的真实规模。心跳与连接类心跳上报成功率、平均心跳延迟、最近心跳分布。这两个指标能快速区分网络抖动和 Agent 进程假死。任务执行类排队中任务数、执行中任务数、任务成功率、平均执行时长。资源与异常类CPU/内存均值、指令超时次数、异常退出次数、Agent 版本分布。我们在第一期只做了前三组结果上线后发现少了一个关键视角版本分布。有一次新版本 Agent 灰度引入内存泄漏老版本都正常新版高负载时不稳定。没有版本维度的大屏只会看到“某区域 Agent 在线率下跌”排查很久才定位到是版本问题。所以版本分布这事后期又被塞进了大屏的辅助区域虽然不大但真的救命。2.2 指标的采集口径一个半小时的返工教训指标定下来之后更大的坑在于采集口径。我们当时因为多套系统之间的定义不统一吃过很大的亏。具体来说任务成功率有两种算法一是从 Harness 的数据库里统计指令状态为成功的总数除以总数二是从每个 Agent 上报的事件日志里统计成功事件数除以事件总数。前者偏向最终状态后者偏向过程记录。由于 Agent 重启或重试的问题这两个分母并不一样一度导致大屏的数据和明细后台对不上。后来我们固定了一条规则一切以 Harness 层落库的“任务状态流转记录”为唯一数据源Agent 上报事件仅作为辅助证据。到这一步我才理解做可视化项目时图表美术只是壳指标口径的一致性才是骨架。每个指标在画上去之前必须写清它的定义公式、采集源、时间窗口。宁可花一天做指标字典也别上线后花一周对数据。2.3 标签设计决定了后续能怎么“切”在设计存储和图表时要预先考虑好需要从哪些维度筛选。我建议每个 Agent 运行时至少带上这几类标签集群/区域版本号操作系统和架构Agent 所在宿主机或 Pod负责的业务线有了这些标签大屏的数据才能被灵活切片。比如你后来想做一个“按业务线查看当前 Agent 成功率”的视图就不需要重新改造上报格式只要查询时按 label 过滤即可。这套思路和 Prometheus 的时间序列模型很像指标名 标签集合就是唯一的时间序列标识。3. 数据链路与实时计算从 Agent 上报到大屏渲染3.1 Agent 主动上报和中心拉取到底选哪个到这里指标清单有了接下来是数据的“运输问题”。Harness 层和 Agent 之间通常已经存在长连接或 HTTP 轮询。如果是长连接更适合做服务端推送监控如果是短连接可以采集心跳但难以做到精确的在线状态。我们的 Agent 选择的是 MQTT 长连接和 Harness 的 Broker 保持心跳。这样在线状态基本是准实时的无需再去额外扫描服务器端口。与之配套的还有一套兜底机制若 MQTT 通道断开Agent 本地会缓存最近的任务执行日志恢复后自动重传。这在实现监控时价值很大因为它能解释“为什么 Agent 显示在线但数据很久没更新”的情况。另外有个经验大屏上“Agent 在线数”统计的并不是 MQTT 的连接数而是最近 5 分钟内有有效心跳的 Agent 个数。MQTT 连接可能处于半开状态连接没断但收不到数据如果只看连接数会掩盖一部分假死问题。这个规则我们在数据接入层统一处理避免开发图表时每个模块各自写一套“在线”判断。3.2 实时计算链路选型Kafka 流处理 Redis 时间序列库画大屏的数据链路我最推荐的是下面这条组合拳Agent 通过 MQTT/HTTP 把状态上报到 Harness 网关网关校验后写入 Kafka。使用 Kafka Streams 或者轻量的消费者程序对消息做清洗、聚合计算 1 分钟粒度的心跳成功率、任务成功率、平均耗时。聚合结果写入 Redis用于大屏实时显示当前值和时序数据库用于趋势图和历史回放。大屏服务端通过 WebSocket 订阅 Redis 的变更事件推送数据到前端。你可能想问为什么不能直接让大屏查 DataFrame 或者查 MySQL原因很简单大屏的加载频率特别高如果每次整屏刷新都打到业务库会给正常业务带来无谓的压力。Harness 层的数据库必须保证核心写入性能不能承担频繁聚合查询的负担。时序库我们用的是 VictoriaMetrics选它不选别的主要是上线成本极低单机模式就能扛住每秒几十万的指标写入而且兼容 PromQL查询语法生态齐全。当时也纠结过要不要直接上 ClickHouse后来想通了我们大屏核心是在线数和成功率这种流式聚合不是海量明细的随意切片分析VictoriaMetrics 的定位更贴合需求。3.3 为什么最终没有用统一网关存所有日志第一版架构里我心血来潮想把 Agent 执行产生的所有日志也走 Kafka 存下来用于“大屏上看日志预览”。后来发现代价很高很容易把大屏这个“状态可视化系统”做成一个“日志搜索系统”预算和精力分配都崩了。想清楚后我们做了个取舍大屏只接收结构化的指标和轻量事件比如状态变更、任务开始结束、异常码而完整执行日志仍走独立的文件或日志平台。监控大屏的核心能力是在一堆状态里快速发现异常而不是提供逐行日志阅读的沉浸体验。如果想看某异常 Agent 的细节在大屏上点击一个节点跳转到日志平台带参查询即可没必要把两个系统硬揉在一起。4. 大屏前端实现可视化框架选择与显示细节4.1 可视化图表库选型ECharts 为主体Canvas 为辅助到了前端部分这才是很多人印象里的“可视化大屏”工作。我们选型时对比了一阵。主框架用的是 Vue 3这一层因团队熟悉度不同没有绝对标准。重点是图表库我们选择了 Apache ECharts。理由有三点内置地图和雷达图等图表类型多官方文档全社区踩坑案例多在大数据量下支持 Canvas 渲染而不是 SVG节点几千个时依然流畅。偶尔需要极高性能的节点拓扑时再用 Canvas 手写绘制比如“全网 Agent 连接拓扑”并不是常开而是作为辅助 tab 存在。如果你还在犹豫选 ECharts 还是 AntV我的建议是先看团队更熟悉哪个。它们能力都很强。但如果你可能用到自定义大屏背景和复杂的飞线效果ECharts 能省不少事如果有比较强烈的统计分析需求AntV 的统计图表会更顺手。4.2 大屏页面结构设计状态总览、趋势、节点拓扑监控大屏不是一屏展示越多越好。我们做了三块区域中央主视图显示 Harness 层管理下的 Agent 集群实时在线率配一张按区域分布的缩略地图用色阶从绿到红展示健康度。左侧趋势区当前时刻往前推 24 小时的任务成功率、心跳延迟变化方便观察长期趋势。右侧异常列表区实时滚动显示离线 Agent 和高延迟 Agent。为何这样布局观察顺序是先看整体健康状态再横向对比时段趋势最后下钻到具体异常实体。我们在实际试运行中收到不少好评因为操作人员不用来回切换 Tab 就能完成“感知异常—确认范围—点击进入详情”三步。4.3 接口推送方案用 WebSocket 代替轮询在数据刷新上高实时大屏最主要的一个经验是不要用 setInterval 每 5 秒拉一次全量接口。否则当页面放大到大屏 4K 分辨率时浏览器帧率会明显掉下来。我们的做法是页面初载时调用一次 HTTP 接口拿全量基础数据之后只通过 WebSocket 接收增量推送。每个推送消息带有自增时间戳前端去重后每 2 秒合并进图表的数据集。这样既减轻后端压力也让帧率保持稳定。同时WebSocket 自动断线重连逻辑必须做而且要处理“重连后立即拉取一次全量同步”避免断线期间图表数据产生空洞。4.4 视觉呈现的细节不是越炫越好很多网上的“可视化大屏背景”预设第一眼看着很酷但放到业务状态监控上未必合适。大量的渐变、粒子动画虽然适合展厅大屏却对日常盯守是一种干扰。我们的取舍原则是只有状态异常时使用醒目的红色或闪烁提醒正常状态尽量用偏冷淡的蓝绿色。图表边框尽量细背景使用深色但不必有好几层光晕。这样做的目的是让值班人员扫一眼就能判断“这个系统是否正常”而不是每次都要仔细辨析颜色深浅。5. 实操中避不开的坑状态漂移、数据不一致与告警疲劳5.1 状态漂移显示的在线和实际不一致在这类监控项目中最常见的坑就是“状态漂移”。比如大屏显示 Agent 在线但实际 Agent 已经假死不再执行任务。造成这种问题的原因通常是心跳机制不够严格。心跳和真实能力无关一个阻塞在 IO 上的 Agent 依然能发送心跳。我们在心跳之外增加了“任务探活”Harness 每 30 秒随机选择少量 Agent 发送一个轻量级的 ping 指令并要求收到 pong 响应。只有心跳成功且最近 ping 响应正常的 Agent 才被标记为“健康”。大屏上展示的在线率改成健康率比单纯在线率更有操作指导意义。5.2 大屏数据对不上明细系统数据不一致问题在很多可视化项目里都存在。我们已经要求统一指标口径但还有另一个常见来源时间窗口和时区。比如任务成功率如果按开始时间聚合那跨天任务会算到前一天还是后一天不同报表之间会有差异。大屏数据与 Excel 报表不一致的问题常有人理解成“大屏显示错了”实则不是错而是聚合维度不同。这次我们专门统一了所有数据产品的默认口径窗口按 Agent 任务结束时间归入当天统计。这一点建议越早定越好最好在项目的指标字典里直接写明。5.3 监控大屏没人看、报警风暴的连锁反应一个独立监控大屏最容易产后失去价值不是说不再显示而是大家都习以为常。上线第一周新鲜感还在到了第四周基本没人主动看。启动原因往往是所有该暴露的问题都被告警轰炸过已经麻木。我们的应对措施是给大屏加了一个“温和升级”机制对于离线 Agent按照两个等级展示一个是瞬时断连、一个是持续离线超过 10 分钟。只有持续离线才会触发严重告警。同时在页面顶部留出一行“最近 1 小时恢复”的指标让团队看到我调整配置后发生的问题确实在减少形成正向反馈。坦白说这部分已经超出了“做图表”的范畴但正是这种产品化思维让大屏最终真正成为大家每天开会都会扫一眼的地方。6. 上线后的最佳实践与迁移扩展建议任何平台都不可能一成不变。Harness 层监控大屏跑了一段时间后会有几个重要的扩展方向。其一是做 Agent“状态预测”。我们通过时序库中保存的历史数据对 Agent 离线趋势做了简单回归预测比如未来半小时内某区域的 Agent 离线率可能超过阈值系统提前给出预警。实现思路不复杂但收益明显优于事后告警。需要注意的是预测仅适合作为参考不要直接驱动自动运维动作避免误操作影响业务。其二是把可视化能力开放给业务方。我们提供了类似 SQL 查询的 API让各业务线可以自行拉取他们关心的 Agent 专属指标而不必每个需求都改动大屏。大屏本身只维护一套统一基线视图细节交给自助分析。第三个和前面说到的实时链路相关如果在当前架构下 Kafka 消费能力成为瓶颈优先检查和调整分区数而不是盲目抬高消费线程。出现积压时在大屏数据流上有滞后感却不能丢数据这是我们实际的经验具体分区策略要按上报量峰值来判断没有统一最好的配置只有最匹配当下来流量模型的配置。最后提醒一句这种 Harness 层监控可视化项目最怕一步到位。第一版可以做概要视图把在线率、成功率、离线数这几个核心指标跑通第二版再考虑节点拓扑下钻和异常归类。先把链路打通确定数据可靠的根后面视觉层的东西都是锦上添花。