docs: 补充 Workbench 性能 SLO 治理 (#505)
Co-authored-by: Codex <codex@noreply.local>
This commit is contained in:
Lyon
@@ -50,6 +50,7 @@ Workbench性能负责把 HWLAB Cloud Web 工作台中用户直接感知的等待
|
||||
- UniDesk YAML-first ops 形式的 D601 v0.3 Workbench 监控接入、scrape/render/status/summary CLI、告警/recording rule 配置和受控运维验证。
|
||||
- D601 v0.3 Cloud Web `/performance` 性能监控工作台：以同一权威 summary/series 数据源展示中文化概览卡、趋势图、分布图、TopN 排行、数据新鲜度、采集健康和可访问表格 drill-down。
|
||||
- dashboard 图表、表格、tooltip、legend、空状态、错误状态、加载状态、单位、状态和既有数值的中文化展示；默认 UI 不直接暴露未经产品确认的英文 raw 值。
|
||||
- SLO、阈值、告警准入和持续治理分流：用户可见 Performance 页只呈现窗口化性能事实和数据质量，内部告警只基于稳定 metric family、足够样本、持续窗口和 YAML 声明阈值触发。
|
||||
|
||||
### 2.3 范围外
|
||||
|
||||
@@ -81,6 +82,8 @@ Workbench性能负责把 HWLAB Cloud Web 工作台中用户直接感知的等待
|
||||
| 桶化估算 | 从 histogram bucket 推导出的近似分位。它必须显式标记 `approximation=bucketed` 或等价字段，并提供 bucket 边界或估算说明；不得显示成精确耗时。 |
|
||||
| 低样本 | 当前窗口内样本数量不足以支持健康判断。低样本是可信度状态，不是慢路径根因，也不能被升级为阻塞或正常结论。 |
|
||||
| 采集健康 | 当前窗口观测是否足够新鲜、是否有样本、是否可聚合的状态；它来自同一权威 summary 的数据质量字段，不是第二套 collectorStatus 事实源。 |
|
||||
| SLO | 面向运维治理的服务目标口径，由 metric family、统计窗口、最低样本、持续时间、阈值、严重级别和处置入口组成；具体数值以 UniDesk owning YAML 为准。 |
|
||||
| 告警准入 | 指一个指标进入内部告警前必须满足的可信度条件，包括样本数量、freshness、窗口持续性、sourceFamily 和采集健康；低样本或暂无数据默认不能触发性能慢路径告警。 |
|
||||
| 性能监控工作台 | Cloud Web `/performance` 中面向管理员和值守人员的 dashboard 视图，用概览卡、趋势、分布、排行和表格 drill-down 展示 Workbench/RUM/API/Long Task 性能健康。 |
|
||||
| 低基数 label | Prometheus label 只能取有限稳定集合，例如 route template、journey、phase、eventKind、status，不包含 traceId、sessionId、runId 或用户输入。 |
|
||||
| YAML-first UniDesk ops | UniDesk 自有运维事实先进入 YAML，再由受控 CLI 渲染、校验和下发；运行面对象只作为观测面，不反推配置真相。 |
|
||||
@@ -280,6 +283,7 @@ session 切换必须分别记录 `first_visible` 和 `full_load`。first visible
|
||||
| PJ2026-0106050509 | 权威观测 | 本规格 6.9 | observation history、metric family、windowed summary 和跨族不可覆盖边界 | 运维监控、Web工作台、API契约 | `/performance`、告警、审计 |
|
||||
| PJ2026-0106050510 | 窗口质量 | 本规格 6.10 | 时间窗口、样本数、freshness、aggregationKind、approximation 和 lowSample 语义 | 运维监控、API契约 | dashboard、TopN、drill-down |
|
||||
| PJ2026-0106050511 | 分叉禁令 | 本规格 6.11 | 禁止 collectorStatus 旁路、读侧 repair、fallback、bucket 上界冒充精确值和跨族仲裁 | Workbench唯一投影、Web工作台 | 后续迁移和回归 |
|
||||
| PJ2026-0106050512 | SLO治理 | 本规格 6.12 | SLO、阈值、告警准入、用户可见页面和内部告警职责分离 | 运维监控、YAML运维 | 持续治理和维护 issue |
|
||||
|
||||
## 6. 原子需求
|
||||
|
||||
@@ -415,8 +419,22 @@ Performance 页必须吸收 Workbench 唯一投影的失败教训：不得在 We
|
||||
|
||||
迁移阶段必须删除或改写旧的分叉路径。旧 summary 缺少窗口字段、近似字段或 source family 时，不得由前端补造；旧 bucket 上界显示、二次单位换算、localStorage 真相、raw metrics fallback、hidden probe repair 和 collectorStatus 仲裁都应作为 P1/P4 的负向扫描对象。任何保留的临时兼容都只能作为只读审计输入，不能参与默认 dashboard 展示。
|
||||
|
||||
### 6.12 OPS-WBPERF-REQ-012 SLO 与持续治理
|
||||
|
||||
| 编号 | 短名 | 主责模块 | 关联模块 |
|
||||
| --- | --- | --- | --- |
|
||||
| OPS-WBPERF-REQ-012 | SLO治理 | PJ2026-0106050512 SLO治理 | [运维监控](PJ2026-010605-observability-monitoring.md)、[YAML运维](PJ2026-010603-yaml-first-ops.md)、[Web工作台](PJ2026-010401-web-workbench.md) |
|
||||
|
||||
Workbench 性能 SLO 只能基于稳定 metric family、明确窗口、足够样本、持续时间和 YAML 声明阈值触发。SLO 配置应至少声明 `metricFamily`、`journey` 或 `routeTemplate`、统计方法、窗口、最低样本、freshness 要求、阈值、持续时间、严重级别、处置入口和 owner；具体数值、窗口长度和告警路由以 UniDesk owning YAML 为准，SPEC 不硬编码数值。
|
||||
|
||||
用户可见 `/performance` 页面和内部告警必须分清职责。Performance 页展示窗口化事实、趋势、TopN、数据质量和中文诊断，允许显示 `低样本`、`暂无数据`、`采集降级`、`桶化估算` 或 `精确窗口分位`；内部告警只在告警准入满足时触发，不得把低样本、暂无数据、刚发布后的冷启动窗口或单个 synthetic probe 失败直接升级为“性能阻塞”。采集链路本身持续缺样、stale 或 ingest failure 时，应进入采集健康/观测可用性告警，而不是伪造成某个 API 或 Workbench journey 慢路径。
|
||||
|
||||
后续改进 issue 必须按职责分流。用户可感知变慢且满足 SLO 准入时，创建性能退化 issue，正文写清 metric family、窗口、样本、sourceFamily、route/journey、阈值来源和 public origin 复测入口；采集缺失、freshness stale、summary API 错误或 Prometheus target 异常时，创建采集健康 issue；新增 metric family、summary schema、dashboard 合同或告警策略变更时，创建 SPEC/架构治理 issue。大型计划不得只落在已有 issue 评论区；必须创建独立 issue，并在父级治理 issue 中只保留短链接和当前状态。
|
||||
|
||||
每次关闭 Workbench 性能实现或维护 issue 时，closeout 必须说明是否影响 SLO 或告警准入：若影响，回写对应 YAML/source branch、SPEC 引用版本、D601 v0.3 public `/performance` 验收、负向分叉扫描和 rollout 证据；若不影响，说明 `SLO impact=none` 或等价结论。历史数据和当前窗口必须分开判断，不能用全量历史混合近期修复效果，也不能用短窗口低样本替代稳定窗口结论。
|
||||
|
||||
## 7. 过程控制
|
||||
|
||||
本规格的执行 issue 为 [#1392](https://github.com/pikasTech/HWLAB/issues/1392)，性能问题修复执行 issue 为 [#1422](https://github.com/pikasTech/HWLAB/issues/1422)，Performance dashboard 中文化可视化执行 issue 为 [#1609](https://github.com/pikasTech/HWLAB/issues/1609)，单一权威观测模型架构治理 issue 为 [#1638](https://github.com/pikasTech/HWLAB/issues/1638)，P0 SPEC 先行 issue 为 [#1639](https://github.com/pikasTech/HWLAB/issues/1639)。该类 issue 的 P0 阶段必须以本 SPEC 为前置：先确认本规格、父级 [PJ2026-010605 运维监控](PJ2026-010605-observability-monitoring.md)、[PJ2026-010401 Web工作台](PJ2026-010401-web-workbench.md)、[PJ2026-0104010803 Workbench唯一投影](PJ2026-0104010803-workbench-unique-projection.md) 和 [PJ2026-010403 API契约](PJ2026-010403-api-contract.md) 的引用关系，再进入后续实现。
|
||||
本规格的执行 issue 为 [#1392](https://github.com/pikasTech/HWLAB/issues/1392)，性能问题修复执行 issue 为 [#1422](https://github.com/pikasTech/HWLAB/issues/1422)，Performance dashboard 中文化可视化执行 issue 为 [#1609](https://github.com/pikasTech/HWLAB/issues/1609)。单一权威观测模型架构治理 issue 为 [#1638](https://github.com/pikasTech/HWLAB/issues/1638)，阶段执行 issue 为 P0 [#1639](https://github.com/pikasTech/HWLAB/issues/1639)、P1 [#1641](https://github.com/pikasTech/HWLAB/issues/1641)、P2 [#1640](https://github.com/pikasTech/HWLAB/issues/1640)、P3 [#1642](https://github.com/pikasTech/HWLAB/issues/1642)、P4 [#1643](https://github.com/pikasTech/HWLAB/issues/1643) 和 P5 [#1644](https://github.com/pikasTech/HWLAB/issues/1644)。该类 issue 的 P0 阶段必须以本 SPEC 为前置：先确认本规格、父级 [PJ2026-010605 运维监控](PJ2026-010605-observability-monitoring.md)、[PJ2026-010401 Web工作台](PJ2026-010401-web-workbench.md)、[PJ2026-0104010803 Workbench唯一投影](PJ2026-0104010803-workbench-unique-projection.md) 和 [PJ2026-010403 API契约](PJ2026-010403-api-contract.md) 的引用关系，再进入后续实现。
|
||||
|
||||
后续实现 issue 或 PR 收口时必须回写：使用的 SPEC 编号和实现引用版本、触达的源码文件头部标注情况、Prometheus 指标/label 审查结果、D601 v0.3 public origin 的原入口验证结果，以及是否需要继续修订本规格。
|
||||
|
||||
Reference in New Issue
Block a user