Skip to content

每个插件都可独立观测的指标设计 ​

文档导航 · 现有上报能力

状态:待实现提案。本页提出不同插件的观测契约、统计语义与通用展示方式,不是当前配置参考或可调用 API。插件之间的数据结构和统计逻辑可以不同。

目标和适用边界 ​

插件接入的交付物是完整的观测契约:身份与能力声明、事实 schema、统计语义、展示描述和验收样本。只有 emit 接口不足以完成接入。

平台保证已登记/已发现插件都有可见入口、数据状态和运行明细;满足受支持声明协议的插件可以获得通用统计页面。不能自动推断任意 JSON 的业务含义。复杂领域统计允许扩展服务端投影,但不能让未实现的专项图表遮蔽插件基础状态与事实明细。

完全未连接过服务端的安装,其插件清单无法被远端凭空发现。页面基于最近确认的清单、声明及事实展示,明确 asOf 和可观测范围,不承诺断网期间实时获知本地队列状态。

一、插件目录独立于业务事件 ​

宿主在会话启动和插件集合变更时上报插件清单:稳定 pluginId、displayName、pluginVersion、enabled、受支持的观测契约版本,以及该安装/项目范围和快照时间。清单快照要有版本/顺序,迟到快照不能覆盖更新状态。

目录不能靠“哪些插件已经产生业务数据”推导,否则已启用但从未触发、加载失败和不支持采集的插件会消失。已登记的插件定义与最近清单相结合,可以区分可用、观测到已安装、已禁用、加载失败、未知。没有后续清单不等于插件已经卸载。

同一插件跨项目/安装可能有不同版本和状态;总览显示版本分布与范围,不用一个全局 enabled/status 覆盖所有实例。项目级启动和后台运行允许没有 taskInstanceId,不能为了满足任务报表而制造任务。

二、所有插件共有的观测 ​

由宿主自动采集,不要求插件自行埋点:

  • 生命周期运行:pluginRunId、stage、开始/结束、耗时、插件版本、任务/会话/阶段(如适用)。异步运行在开始时冻结归属。
  • 运行结果:完成、异常、取消、不完整;业务判定或 gate 阻止单独记录,不能把测试未通过等同于插件崩溃。
  • 数据处理状态:已知接收/投影数量、拒绝原因、最近收到数据时间、查询数据截至时间。客户端已知的 pending/dropped/quarantined 以最后一次成功报告的快照展示,带采样时间。
  • 未触发、不支持采集、上报关闭、无本期样本、部分数据、契约不兼容分别有明确文案;无数据不是 0,上传成功也不是业务成功。

运行状态、业务结果、传输/处理健康分别展示,不能压成一个绿色或红色状态。事件驱动插件长期没有新数据不直接判为异常;只有声明了周期及期望频率的采集才可判定过期,其他显示最后观测时间和未知状态。

三、插件专属观测契约 ​

平台维护经过校验的 descriptor registry。插件包声明需要的 descriptor 标识和版本,服务端负责解析可接受契约;不能因为匿名客户端上传了一个描述就覆盖其他插件的定义,也不从事件中的任意 URL 下载或执行描述。

每个 descriptor 至少包含:

内容必须说明
身份pluginId、descriptorVersion、兼容的事件 schemaVersion;插件发布版本独立记录
事实eventType、字段类型、必填/可缺失、稳定业务事实键、关联 run/task、发生时间
指标metricKey、中文名称、含义、单位、统计粒度、来源字段、空值解释
统计去重键、聚合算子、维度、时间归属、筛选口径、快照或增量语义
比率分子/分母及配对范围、零分母处理;不能直接平均百分比
维度可分组字段、枚举/基数上限;taskId/runId 用于追溯而非无限展开图例
展示分组、指标卡/趋势/分布/表格、列名、格式、默认视图和解释文案
能力required/optional、按运行类型适用性、未采集/不适用原因、周期性采集的期望频率

首批聚合原语覆盖:去重计数、增量求和、按实体取最新快照、分布/分位数、分子分母比率、分类结果和有界明细表。前端不执行任意计算表达式,所有聚合在服务端完成。

例如覆盖率的“最新值”必须按包/输入版本/检查类型等可比较范围选取,不能把多次运行覆盖率相加。耗时分位数须来自可合并的样本/分布,不平均各批次 P95。不同语义版本不混算;descriptor 修改语义必须升版本,历史数据保留原解释。

普通插件新增支持范围内的指标,只需提交声明、采集事实和契约样本,不需要为每个插件修改仪表盘。超出原语的业务计算需要注册服务端 projector;超出通用视图的表现可增加平台维护的 renderer,但基础指标和明细先可见。页面不加载插件提供的任意 JavaScript/HTML。

四、查询与仪表盘 ​

建议查询提供两个逻辑 DTO,具体路由实施时确定:

  1. 插件目录:按项目/安装范围返回已登记与已观测插件、名称、版本分布、能力、状态、最近数据时间。
  2. 插件报告:包含 descriptorVersion、period、filters、asOf、projectionVersion、completeness;分别返回运行概览、业务指标、数据健康和分页运行明细。每个指标携带 value/null、单位、样本数、适用/缺失数量及原因。

页面固定为“插件总览 → 插件详情 → 某次运行/关联任务”:

  • 总览:每个插件一行/卡片,显示名称、版本、是否有本期运行、运行异常、数据完整性及少量声明的核心业务指标。
  • 详情:统一运行概览;根据 descriptor 渲染插件专属指标、趋势和分组;单独显示数据健康;运行明细可追溯任务、阶段与版本。
  • 任务详情:反向列出本任务涉及的插件及运行结果,并链接相同插件报告,统计和身份不另算一套。

示例均用于说明可扩展性,除 quality-web 外不表示现有插件:

插件示例专属业务指标通用视图
quality-web用例通过/失败/跳过、按包覆盖率、检查结果结果分布、覆盖率表、检查运行明细
依赖审计插件不同严重级别问题、扫描包数、修复结果分类分布、趋势、扫描记录
文档校验插件检查文件数、失效链接、规则命中指标卡、规则分布、校验记录

五、兼容与缺失的可见性 ​

  • 未注册/不支持的事件版本:拒绝/隔离保持可诊断,基础插件入口仍来自目录;显示缺失能力和拒绝原因,不宣称所有业务数据已接收。
  • 描述已识别但高级视图不可用:使用字段标签、单位和明细表降级,并显示能力限制。
  • 某次运行不适用或没有可选数据:返回原因与 null;不能自动补 0 或用其他运行值冒充本次结果。
  • 没有接收到客户端健康快照:服务端只能展示自身可知的接收/处理状态;本地待发送量为未知,并指引本地诊断入口。
  • 插件变更/禁用:历史数据和旧 descriptor 继续可查;本期状态不能覆盖历史状态。

六、实施与验收 ​

实施建议:先做目录和宿主通用生命周期,再做 descriptor/注册校验/通用聚合与查询,随后做通用仪表盘,最后让 quality-web 接入并用两个不同领域的测试插件验证扩展性。迁移 quality-web 时复用稳定事实 ID,避免旧专用分支和新通用路径双计数。

验收必须覆盖:

  1. 已启用但零次运行、禁用、加载失败、不支持采集的插件均有可理解的入口与状态。
  2. 至少三个业务结构不同的插件通过各自声明展示专属指标,新增支持范围内的测试插件无需修改仪表盘源码。
  3. 业务失败/插件异常/上报失败分别可见,不相互替代;无数据、不适用和真实 0 可区分。
  4. 相同事实重复上传、乱序和丢 ACK 不重算;快照不累加、比率不直接平均,作用域不同的数据不误合并。
  5. 多项目、多安装、跨版本和后台无任务运行的归属正确;异步结束不串任务。
  6. 描述缺失、旧版前端、新版 schema、服务端投影失败、离线、禁用后查看历史均有明确状态,不能静默消失。
  7. 通用组件对声明中的名称和文本安全渲染;字段/维度/行数有界,查询分页,未登记描述不能覆盖现有定义。

这里只确立设计和验收要求,尚未实现目录、descriptor 协议或通用插件仪表盘。