diff --git a/project-management/PJ2026-01/specs/PJ2026-010605-observability-monitoring.md b/project-management/PJ2026-01/specs/PJ2026-010605-observability-monitoring.md index 8df24e8a..ba5b4ee6 100644 --- a/project-management/PJ2026-01/specs/PJ2026-010605-observability-monitoring.md +++ b/project-management/PJ2026-01/specs/PJ2026-010605-observability-monitoring.md @@ -33,6 +33,8 @@ 本课题的目标状态是：各业务 L1 提供自己的服务健康和业务状态指标，平台运维统一接入 Prometheus 并输出可查询、可告警、可回溯的运维状态；监控只判断运行面健康和资源状态，不替代业务成功标准。 +运维监控接入必须遵循 UniDesk YAML-first ops：scrape target、alert rule、recording rule、summary query、target/node/lane、namespace、endpoint、采样/保留/阈值等 UniDesk 自有运维事实必须归属 YAML；受控 CLI 负责读取、校验、渲染、apply/status/summary。运行面对象和 Prometheus 查询结果只作为观测证据，不反推为配置真相。 + ### 2.2 范围内 - Prometheus scrape target、metrics endpoint、alert rule 和服务健康指标接入。 @@ -53,6 +55,7 @@ | --- | --- | | Prometheus 运维监控 | 通过 Prometheus 采集、查询和告警 HWLAB 运行面 metrics 的运维能力。 | | 用户可感知性能 | 用户在 Web、CLI 或 API 入口中直接感受到的等待时间、加载时间、首个可读内容出现时间和完整可用状态。 | +| YAML-first 运维监控 | Prometheus scrape、rule、summary 和 target 归属先进入 UniDesk YAML，再通过受控 CLI 渲染和验证的运维形态。 | | scrape target | Prometheus 抓取 metrics 的目标服务、path 和 label 集合。 | | metrics endpoint | 服务暴露运行状态、资源状态和业务健康指标的 HTTP 端点。 | | alert rule | 对 metrics 表达告警条件的规则，具体阈值来自配置。 | @@ -90,7 +93,7 @@ 运维监控应接入 HWLAB 各运行服务的 metrics endpoint 和 scrape target，使服务 live、ready、resource、queue、error、latency 和依赖健康可以被 Prometheus 查询。 -各 L1 负责定义自身服务健康指标含义；平台运维负责统一接入、命名、label 和可查询状态。metrics 缺失应暴露为监控缺口，不得用日志 grep、一次性 curl 或人工截图替代长期监控。 +各 L1 负责定义自身服务健康指标含义；平台运维负责通过 YAML-first UniDesk ops 统一接入、命名、label 和可查询状态。metrics 缺失应暴露为监控缺口，不得用日志 grep、一次性 curl、手工 `kubectl apply` 或人工截图替代长期监控。 ### 6.2 OPS-MON-REQ-002 告警规则 diff --git a/project-management/PJ2026-01/specs/PJ2026-01060505-workbench-performance.md b/project-management/PJ2026-01/specs/PJ2026-01060505-workbench-performance.md index 10305a65..104614ed 100644 --- a/project-management/PJ2026-01/specs/PJ2026-01060505-workbench-performance.md +++ b/project-management/PJ2026-01/specs/PJ2026-01060505-workbench-performance.md @@ -35,6 +35,8 @@ Workbench性能负责把 HWLAB Cloud Web 工作台中用户直接感知的等待 本规格的目标状态是：用户从 Web 发起动作后，浏览器、Cloud API、Workbench SSE、trace/read model、AgentRun adapter 和 Prometheus 之间拥有同一套低基数性能事件口径；平台运维可以用这些指标判断 D601 v0.3 Workbench 是否变慢，客户端和 Agent编排可以用同一 traceId/runId 的脱敏诊断继续定位，但监控本身不替代业务功能闭环。 +相关运维必须按 UniDesk YAML-first ops 设计：scrape target、recording rule、alert rule、dashboard summary、Prometheus 查询 endpoint、采样/保留/阈值和 D601 node/lane 归属都进入 UniDesk owning YAML；受控 UniDesk CLI 只负责读取 YAML、校验结构、渲染计划、apply/status/summary，并通过共享 ops helper 执行。运行面 Kubernetes 对象、Prometheus target 状态和 Grafana/Prometheus 查询结果只能作为观测对象，不得反向成为配置 source of truth。 + ### 2.2 范围内 - 用户发出消息到首个 Code Agent 消息或工具调用在 Web 可见的耗时。 @@ -43,6 +45,7 @@ Workbench性能负责把 HWLAB Cloud Web 工作台中用户直接感知的等待 - 用户首屏打开 Workbench 时，第一个可操作/可读内容出现时间，以及工作台关键数据全部加载完成时间。 - Workbench REST、SSE、trace pagination、turn snapshot、API proxy、AgentRun adapter 操作的常规 RED 指标。 - 前端 RUM 与后端 Prometheus 指标的关联键、脱敏边界、低基数 label、histogram bucket、recording rule 和低样本告警边界。 +- UniDesk YAML-first ops 形式的 D601 v0.3 Workbench 监控接入、scrape/render/status/summary CLI、告警/recording rule 配置和受控运维验证。 ### 2.3 范围外 @@ -64,6 +67,7 @@ Workbench性能负责把 HWLAB Cloud Web 工作台中用户直接感知的等待 | RUM | 浏览器端 Real User Monitoring，通过 Web Performance API、Navigation Timing、Long Task、SSE 接收和 DOM paint ack 采集真实用户性能。 | | Server-Timing | HTTP 响应头中的阶段耗时摘要，用于把 API 总耗时拆成 read model、DB、AgentRun adapter、projection 等后端阶段。 | | 低基数 label | Prometheus label 只能取有限稳定集合，例如 route template、journey、phase、eventKind、status，不包含 traceId、sessionId、runId 或用户输入。 | +| YAML-first UniDesk ops | UniDesk 自有运维事实先进入 YAML，再由受控 CLI 渲染、校验和下发；运行面对象只作为观测面，不反推配置真相。 | ## 4. 系统边界和接口 @@ -106,6 +110,14 @@ flowchart LR PERF --> MET end + subgraph UniDeskOps[UniDesk YAML-first Ops] + YAML[owning YAML] + CLI[ops CLI plan/apply/status/summary] + HELP[shared ops helpers] + YAML --> CLI + CLI --> HELP + end + subgraph AgentRun[AgentRun / Backend] EVT[Run Events] CODEX[codex-stdio] @@ -119,6 +131,7 @@ flowchart LR ROUTE -- SSE / REST --> ES API -- REST --> ROUTE RUM -- batched RUM --> PERF + HELP -- scrape/rule/render --> PROM MET --> PROM[Prometheus / Rules / Dashboard] ``` @@ -232,7 +245,8 @@ session 切换必须分别记录 `first_visible` 和 `full_load`。first visible | PJ2026-0106050502 | VisibleAck | 本规格 6.2 | DOM paint ack、first visible、full load 和浏览器 RUM 批量上报 | Web工作台 | 用户体感指标 | | PJ2026-0106050503 | BackendLatency | 本规格 6.3 | AgentRun backend event createdAt 到 Web visible 的端到端投递耗时 | Agent编排、HWLAB接入 | Trace/SSE 性能定位 | | PJ2026-0106050504 | Prometheus指标 | 本规格 6.4 | histogram/counter/gauge、低基数 label、Server-Timing 和 RED 指标 | 运维监控、API契约 | Dashboard、recording rule | -| PJ2026-0106050505 | 代码引用 | 本规格 6.5 | SPEC-first、代码文件头部 SPEC 标注和 issue 回写要求 | 规格治理、全部实现模块 | 后续实现和 review | +| PJ2026-0106050505 | YAML运维 | 本规格 6.5 | UniDesk owning YAML、ops CLI、shared helper、scrape/rule/status/summary 渲染和运行面观测边界 | YAML运维、平台运维 | D601 v0.3 运维监控接入 | +| PJ2026-0106050506 | 代码引用 | 本规格 6.6 | SPEC-first、代码文件头部 SPEC 标注和 issue 回写要求 | 规格治理、全部实现模块 | 后续实现和 review | ## 6. 原子需求 @@ -278,11 +292,23 @@ Workbench性能应至少提供以下 Prometheus 指标族：`hwlab_workbench_jou API 响应可使用 `Server-Timing` 暴露后端 phase 摘要，但该 header 只能包含阶段名和 duration，不包含敏感值或高基数 ID。 -### 6.5 OPS-WBPERF-REQ-005 SPEC-first 与代码引用 +### 6.5 OPS-WBPERF-REQ-005 YAML-first UniDesk ops | 编号 | 短名 | 主责模块 | 关联模块 | | --- | --- | --- | --- | -| OPS-WBPERF-REQ-005 | 代码引用 | PJ2026-0106050505 代码引用 | [规格治理](spec-governance.md)、[Web工作台](PJ2026-010401-web-workbench.md)、[API契约](PJ2026-010403-api-contract.md) | +| OPS-WBPERF-REQ-005 | YAML运维 | PJ2026-0106050505 YAML运维 | [YAML运维](PJ2026-010603-yaml-first-ops.md)、[运维监控](PJ2026-010605-observability-monitoring.md)、[公开入口](PJ2026-010604-public-entry.md) | + +D601 v0.3 Workbench 性能监控的运维接入必须设计成 YAML-first UniDesk ops。owning YAML 应声明目标 node/lane、runtime namespace、metrics services/endpoints、scrape 形态、recording rules、alert rules、summary query、public/raw metrics 暴露边界、采样/保留/阈值和必要 probe；具体数值以 YAML 为准，SPEC 只定义能力和边界。 + +UniDesk CLI 应提供薄 domain 入口，例如 `hwlab nodes observability plan|apply|status|workbench-summary --node D601 --lane v03` 或等价命令。CLI 只校验 YAML 结构、类型、必填项、引用存在性和可渲染性；执行应复用共享 ops helper 做 route 执行、Kubernetes manifest render/apply、Prometheus rule render、bounded query、redacted output 和 summary。禁止把 D601、`hwlab-v03`、Service 名、Prometheus endpoint、阈值、采样窗口或 rule 内容长期硬编码在 CLI 代码中。 + +运行面 Kubernetes 对象、Prometheus target、ServiceMonitor、静态 scrape file、Grafana/Prometheus 查询结果和 pod env 只能作为 presence、health、fingerprint、target 状态或 summary 的观测对象。缺配置时修 owning YAML 和受控 CLI，不得从运行面反推、复制或手工回填 desired state；涉及 Secret 或 token 的输出只允许显示 sourceRef、targetKey、presence、fingerprint、字节数和 redacted 摘要。 + +### 6.6 OPS-WBPERF-REQ-006 SPEC-first 与代码引用 + +| 编号 | 短名 | 主责模块 | 关联模块 | +| --- | --- | --- | --- | +| OPS-WBPERF-REQ-006 | 代码引用 | PJ2026-0106050506 代码引用 | [规格治理](spec-governance.md)、[Web工作台](PJ2026-010401-web-workbench.md)、[API契约](PJ2026-010403-api-contract.md) | 本性能监控能力的实现必须先引用本规格，再进入代码变更。新增或修改的前端、后端、CLI/helper、metrics、RUM、trace adapter 和 dashboard 源码文件头部必须标注遵循的 SPEC 编号、短名和实现引用版本，例如 `SPEC: PJ2026-01060505 Workbench性能 draft-2026-06-17-p0; PJ2026-010401 Web工作台 draft-2026-06-17-r0`，并用一句话说明文件职责。