pikasTech-unidesk/project-management/PJ2026-01/specs/PJ2026-010605-observability-monitoring.md

PJ2026-010605 运维监控

修改历史

版本	对应 commit id	更新日期	变更说明

当前正文仍在规格治理草稿中；未定稿前不新增版本号，不为单次编辑追加 待提交 版本。

正文

PJ2026-010605 运维监控需求规格

1. 文档控制

字段	内容
编号	PJ2026-010605
短名	运维监控
层级	L2 课题
状态	已生效
需求规格模板	ISO/IEC/IEEE 29148 需求规格模板
上级规格	PJ2026-0106 平台运维
规格治理索引	规格治理

本文采用 ISO/IEC/IEEE 29148 需求规格模板的项目裁剪版：正文只保留 HWLAB 运维监控的稳定使命、范围、术语、系统边界、内部分工和原子需求。Prometheus 继续承载 metrics、dashboard、alert 和 Workbench 用户可感知性能指标；OpenTelemetry 首期只承载 tracing、span、trace id 关联和跨服务因果链路。Workbench 用户可感知性能监控的架构图、数据流图、时序图和实现引用要求由 PJ2026-01060505 Workbench性能 细化。

2. 目的和范围

2.1 目的

运维监控负责通过 Prometheus 和 OpenTelemetry 的分工协作采集 HWLAB 运行面 metrics、scrape target、alert rule、服务健康指标、资源指标和关键请求 trace，使平台运维能够发现服务不可用、入口漂移、资源异常、发布后运行状态退化，以及单个 Workbench/AgentRun 请求在 admission、billing、dispatch、projection 或 replay 阶段的失败位置。

本课题的目标状态是：各业务 L1 提供自己的服务健康、业务状态指标和关键链路 trace 语义，平台运维统一接入 Prometheus metrics 面和 OpenTelemetry tracing 面并输出可查询、可告警、可回溯的运维状态；监控只判断运行面健康、资源状态和单次请求因果链，不替代业务成功标准。

运维监控接入必须遵循 UniDesk YAML-first ops：scrape target、alert rule、recording rule、summary query、OTel Collector、trace backend、target/node/lane、namespace、endpoint、采样/保留/阈值等 UniDesk 自有运维事实必须归属 YAML；受控 CLI 负责读取、校验、渲染、apply/status/summary/trace。运行面对象、Prometheus 查询结果和 trace backend 查询结果只作为观测证据，不反推为配置真相。

2.2 范围内

• Prometheus scrape target、metrics endpoint、alert rule 和服务健康指标接入。
• OpenTelemetry Collector、trace backend、span 语义、trace context 传播和 trace 查询入口。
• Web/API/AgentRun/HWPOD/Harness/用户管理等服务的运行面健康、资源状态、公开入口健康和用户可感知性能观测。
• 发布后 runtime readiness、resource usage、error rate、queue depth、target availability 和 alert 状态摘要。
• AgentRun rolling recovery 与 cancel lifecycle 的 active runner、stale lease、cancel request、cancel delivery、terminal report retry、reconciler backlog、projection lag、late-write fencing 和 Job TTL cleanup 观测。
• 监控和 trace 数据的受控查询、低噪声摘要、失败归因和敏感输出约束。

2.3 范围外

• Agent command、CaseRun、HWPOD operation 或用户账本的业务成功标准由对应 L1 定义。
• 完整 prompt、assistant 正文、tool 参数、命令输出、原始日志、测试报告、截图、CaseRun registry 和用户反馈正文不进入本规格或默认 trace attribute。
• Prometheus 具体阈值、保留周期、告警路由、采样间隔和容量数值以 YAML/config 为准，不在本规格硬编码。
• OpenTelemetry Collector image、trace backend image、存储模式、retention、采样率、endpoint 和服务接入关系以 YAML/config 为准，不在业务代码硬编码。
• 监控告警不能代替发布流水、业务验证、CaseRun 评价或用户反馈分流。

3. 术语表

术语	定义
Prometheus 运维监控	通过 Prometheus 采集、查询和告警 HWLAB 运行面 metrics 的运维能力。
OpenTelemetry tracing	通过 OTel Collector、trace backend、span 和 W3C trace context 关联单次请求跨服务因果链路的运维能力。
trace backend	保存并查询 trace/span 的平台组件，首期可由 Tempo 或 Jaeger 承担，部署事实由 YAML 控制。
Trace Explorer URL 模板	由 YAML 声明的 trace backend 打开链接模板，例如包含 {trace_id} 占位符的 Tempo、Jaeger 或 Grafana Explore URL；前端只替换合法 OTel trace id，不拼接其他用户输入。
span	一次请求在 admission、billing、AgentRun dispatch、projection、read/replay 等阶段中的一个可观察工作单元。
trace context	W3C traceparent/baggage 等跨进程传播上下文；业务 traceId/sessionId/runId/turnId 只能作为 span attribute，不能替代标准 trace context。
用户可感知性能	用户在 Web、CLI 或 API 入口中直接感受到的等待时间、加载时间、首个可读内容出现时间和完整可用状态。
YAML-first 运维监控	Prometheus scrape、rule、summary 和 target 归属先进入 UniDesk YAML，再通过受控 CLI 渲染和验证的运维形态。
rolling recovery signal	用于判断 manager/cloud-api rolling 后同一 run/command/runnerJob 是否恢复控制权的低基数 metrics、span attribute 和 CLI 摘要字段。
scrape target	Prometheus 抓取 metrics 的目标服务、path 和 label 集合。
metrics endpoint	服务暴露运行状态、资源状态和业务健康指标的 HTTP 端点。
alert rule	对 metrics 表达告警条件的规则，具体阈值来自配置。
运行健康	服务 ready、live、依赖可达、资源可用和错误率处于可接受状态的运维判断。
业务通过	由业务 L1 原入口定义的功能成功，例如 Agent turn completed、HWPOD operation 成功或 CaseRun 通过。

4. 系统边界和接口

边界项	内容
外部使用者	平台管理员、发布操作人员、值守自动化、需要运行状态的各 L1 owner。
外部输入	服务 metrics endpoint、health/readiness、runtime resource 指标、scrape 配置、alert rule 配置、OTLP trace/span、trace context、trace 查询请求和 metrics 查询请求。
受控资源	Prometheus target、metrics、alert rule、OTel Collector、trace backend、运行面状态摘要、服务健康指标、资源指标和 redacted trace 摘要。
外部输出	target 状态、metrics 查询结果、alert 状态、trace 查询结果、Trace Explorer URL 模板摘要、运行健康摘要、入口健康摘要和 redacted 失败阶段。
用户接口	Prometheus 查询、OpenTelemetry trace 查询、受控平台运维 CLI、发布状态摘要和各 L1 health/status 页面或命令。
系统边界	运维监控负责运行面可观察、告警和单次请求因果链；不定义业务完成标准，不保存默认长证据，不把监控 green 或 trace 可查当作业务通过。

5. 内部分工与规格索引

编号	模块或课题	规格文档	主责边界	上游依赖	下游支撑
PJ2026-01060501	OTel追踪	本规格 6.1	OTel Collector、trace backend、span 语义、trace context 和受控 trace 查询	HWLAB v0.3、AgentRun、用户账本、Web工作台	平台排障、Prometheus 关联
PJ2026-01060502	告警规则	本规格 6.2	alert rule、状态分类和配置来源	Metrics接入、YAML运维	平台值守、发布判定
PJ2026-01060503	运行摘要	本规格 6.3	health、readiness、resource、error rate 和入口健康摘要	公开入口、发布流水	管理员和各 L1 owner
PJ2026-01060504	边界约束	本规格 6.4	监控与业务通过、长证据、敏感输出的边界	全部 L1	用户反馈和排障
PJ2026-01060505	Workbench性能	PJ2026-01060505 Workbench性能	Web 工作台用户可感知性能、RUM、AgentRun event visible latency 和 Prometheus 指标口径	Web工作台、Agent编排、API契约	平台运维、客户端和性能回归调查
PJ2026-01060506	Metrics接入	本规格 6.6	metrics endpoint、scrape target 和 label 口径	各 L1 服务健康指标	Prometheus 查询
PJ2026-01060507	Rolling恢复观测	本规格 6.7	active runner、reconciler backlog、terminal retry、projection lag 和不可恢复 blocker 的查询口径	AgentRun核心、HWLAB接入、Workbench唯一投影、发布Lane	rolling 发布判定、故障收口

6. 原子需求

6.1 OPS-MON-REQ-001 OTel 追踪

编号	短名	主责模块	关联模块
OPS-MON-REQ-001	OTel追踪	PJ2026-01060501 OTel追踪	YAML运维、Agent编排、客户端、用户管理

运维监控应在 platform-infra 提供 YAML-first OpenTelemetry tracing 能力，使一次 Workbench submit 或等价 API 请求可以沿 Cloud API admission、billing preflight、AgentRun dispatch、projection write、trace events read 和 Web replay 等阶段保留可查询 span。

OpenTelemetry 不替代 Prometheus。Prometheus 继续承载 metrics、dashboard、alert 和用户可感知性能指标；OTel tracing 只回答单个 traceId/sessionId/runId/turnId 跨服务断在哪个阶段。业务 ID 可以作为 span attribute 用于排查，但不能成为 Prometheus label，也不能替代 W3C trace context。

6.1.1 目标架构图

flowchart LR
  W[Workbench Web] --> API[HWLAB cloud-api]
  API --> Billing[user-billing]
  API --> AR[AgentRun manager]
  AR --> Runner[AgentRun runner]
  API --> Projection[projection/read model]
  API --> Metrics[Prometheus metrics endpoint]
  Billing --> Metrics
  AR --> Metrics
  API -- OTLP spans --> Collector[OTel Collector<br/>platform-infra]
  Billing -- OTLP spans --> Collector
  AR -- OTLP spans --> Collector
  Runner -- OTLP spans --> Collector
  Collector --> TraceBackend[Trace backend<br/>Tempo or Jaeger]
  Metrics --> Prometheus[Prometheus metrics面]
  CLI[UniDesk platform-infra observability CLI] --> Collector
  CLI --> TraceBackend
  CLI --> Prometheus

6.1.2 数据流图

flowchart TD
  Span[应用关键 span] --> Collector[OTel Collector]
  Collector --> Backend[trace backend]
  Metric[低基数 metrics] --> Prometheus[Prometheus]
  Backend --> TraceQuery[CLI trace query]
  Prometheus --> MetricQuery[CLI metrics/status query]
  TraceQuery --> Diagnose[按 traceId/sessionId/runId 定位失败阶段]
  MetricQuery --> Health[运行健康、趋势和告警判断]
  Diagnose -.关联.-> Health

数据流必须保持职责分离：trace backend 保存高基数字段和跨服务因果链；Prometheus 只保存低基数指标、alert 和趋势。CLI 可以把 metrics 摘要与 trace 查询结果放到同一排障报告中，但不能把两套存储合并为一个第二真相。

6.1.3 关键时序图

sequenceDiagram
  participant W as Workbench
  participant API as cloud-api
  participant B as user-billing
  participant AR as AgentRun
  participant P as projection
  participant OTel as OTel Collector
  participant TB as trace backend

  W->>API: POST /v1/agent/chat
  API->>OTel: span admission
  API->>B: billing_preflight with trace context
  B->>OTel: span billing_preflight
  API->>AR: dispatch command with trace context
  AR->>OTel: span agentrun_dispatch
  AR-->>API: runId/commandId
  API->>P: projection_write
  P->>OTel: span projection_write
  W->>API: replay/read trace events
  API->>OTel: span trace_events_read
  OTel->>TB: export spans

6.1.4 YAML 与 CLI 归属

OTel Collector、trace backend、target route、namespace、image、storage、retention、sampling、export 开关、OTLP endpoint、Trace Explorer URL 模板、probe 和应用接入关系必须进入 config/platform-infra/observability.yaml 或后续确认的 owning YAML。正式入口必须是 bun scripts/cli.ts platform-infra observability plan|apply|status|validate|trace 或等价受控 CLI；trans <target>:k3s 只能作为有界诊断底座，不能成为长期 mutate path。

Trace Explorer URL 模板必须作为 YAML 配置下发到需要展示“打开 Trace”的客户端运行配置中。模板只能包含 {trace_id} 占位符和运维确认的静态 URL 片段；前端替换前必须校验 trace id 为 32 位十六进制字符串。配置缺失、模板禁用或 trace id 非法时，客户端只显示复制入口。任何实现都不得把 trace backend 内部地址、Grafana token、cookie、API key、tracestate、baggage、prompt、assistant 正文或 raw upstream payload 放入模板或用户可见 URL。

首期应用侧手工 span 至少覆盖：

• POST /v1/agent/chat
• durable_admission
• billing_preflight
• agentrun_dispatch
• projection_write
• trace_events_read
• turn_status_read

统一 resource attributes 至少包含 service.name、deployment.environment、unidesk.node、hwlab.lane、k8s.namespace.name 和 git.commit。统一传播使用 W3C traceparent/baggage；traceId、sessionId、turnId、runId、commandId 只能作为 span attribute。

用户可见错误只展示 OTel trace id、request id、route、serviceId、error code、layer 和 redacted observedAt。traceparent 可以作为 HTTP header 传播和返回，tracestate 与 baggage 只能用于受控传播，不得进入用户错误面板、issue closeout 可复制凭据、日志摘要或默认 trace explorer URL。

6.1.5 代码引用规则

本需求范围内新增或修改的源码文件头部必须标注 SPEC: PJ2026-01060501 OTel追踪 draft-2026-06-19-p0，并用一句话说明文件职责。纯 YAML、生成 manifest、锁文件或第三方 CRD 如不能加头部，必须能从 owning YAML、渲染器或 CLI 命令追溯到本 SPEC。

6.2 OPS-MON-REQ-002 告警规则

编号	短名	主责模块	关联模块
OPS-MON-REQ-002	告警规则	PJ2026-01060502 告警规则	YAML运维、公开入口

运维监控应通过配置化 alert rule 表达服务不可达、目标缺失、入口漂移、资源耗尽、错误率异常和发布后健康退化等运维风险。

告警阈值、保留周期、通知路由和采样间隔由 YAML/config 承载；规格只定义告警能力和边界。告警输出应包含服务、target、rule、severity、状态和 redacted 摘要，不输出 Secret、token、DSN password 或完整日志。

6.3 OPS-MON-REQ-003 运行摘要

编号	短名	主责模块	关联模块
OPS-MON-REQ-003	运行摘要	PJ2026-01060503 运行摘要	发布流水、公开入口

运维监控应提供低噪声运行摘要，使平台管理员能查看目标 node/lane 的服务健康、公开入口健康、资源使用、队列积压、错误分类和最近告警状态。

运行摘要用于判断运行面是否需要运维处理或发布回滚，不替代业务原入口。Web 可访问、API health 通过或 Prometheus green 只能证明运行面健康的一部分，不能证明 Agent、HWPOD、CaseRun、用户账本或内测业务用例通过。

6.4 OPS-MON-REQ-004 监控边界

编号	短名	主责模块	关联模块
OPS-MON-REQ-004	边界约束	PJ2026-01060504 边界约束	客户端、Agent编排、硬件池、HarnessRL

运维监控应明确区分运行健康、业务通过和长证据归属。监控只保存和展示运维指标、target 状态和告警摘要；长 trace、CaseRun registry、用户反馈原文、截图和执行日志仍保留在对应业务入口或 GitHub issue。

缺失业务能力时，监控只能报告 blocker 或 health 降级，不能通过新增告警、证据采样或诊断文案伪装成能力完成。

6.5 OPS-MON-REQ-005 Workbench 用户可感知性能

编号	短名	主责模块	关联模块
OPS-MON-REQ-005	Workbench性能	PJ2026-01060505 Workbench性能	Web工作台、Agent编排、API契约

运维监控应把 Web 工作台的用户可感知性能纳入 Prometheus 与 RUM 口径，使用户发消息到首个可见 Code Agent 输出、AgentRun backend event 到 Web 可见、session 切换加载和首屏打开等路径可以被持续观测。

Workbench 性能监控只记录低基数指标、阶段耗时、状态分类和脱敏 correlation；不得把 traceId、sessionId、runId、prompt、assistant 正文、tool 参数、stdout/stderr、Secret 或用户个人信息写入 Prometheus label。具体架构、数据流、时序和代码引用规则由 PJ2026-01060505 Workbench性能 定义。

6.6 OPS-MON-REQ-006 Metrics 接入

编号	短名	主责模块	关联模块
OPS-MON-REQ-006	Metrics接入	PJ2026-01060506 Metrics接入	YAML运维、发布流水

运维监控应接入 HWLAB 各运行服务的 metrics endpoint 和 scrape target，使服务 live、ready、resource、queue、error、latency 和依赖健康可以被 Prometheus 查询。

各 L1 负责定义自身服务健康指标含义；平台运维负责通过 YAML-first UniDesk ops 统一接入、命名、label 和可查询状态。metrics 缺失应暴露为监控缺口，不得用日志 grep、一次性 curl、手工 kubectl apply 或人工截图替代长期监控。

6.7 OPS-MON-REQ-007 Rolling 恢复观测

编号	短名	主责模块	关联模块
OPS-MON-REQ-007	Rolling恢复	PJ2026-01060507 Rolling恢复观测	AgentRun核心、HWLAB接入、Workbench唯一投影、AgentRun发布Lane

运维监控应为 AgentRun/HWLAB rolling recovery 和 cancel lifecycle 提供可查询的低基数 metrics、trace span 和受控 CLI 摘要。最小观测对象包括 active runner 数、runner job observation phase、stale lease 数、cancel request accepted 数、cancel delivered 数、cancel terminalized 数、late-write-fenced 数、terminal report retry/outbox backlog、manager reconciler backlog、reconciler last success/error、projection lag、projection blocker 数、Job TTL cleanup 数和不可恢复 blocker 数。

rolling recovery 相关 span 应能用 OTel trace id/request id 关联 sessionId、traceId、runId、commandId、runnerJobId 和 jobName 的 redacted attribute。高基数业务 ID 只能作为 trace/span attribute 或 CLI 单次查询参数，不进入 Prometheus label；prompt、assistant 正文、tool 参数、stdout/stderr、Secret、完整 token、完整 DSN 和 provider payload 不得进入默认 metrics、span 或 issue closeout。

发布/rollout 前后的受控 CLI 摘要应能回答：仍在运行的 runner 数、已恢复控制权数量、cancel 当前阶段分布、terminal report retry 数、projection lag 最大值、不可恢复 blocker 数和最近一次 reconciler 错误。该摘要只用于定位和发布判定，不替代 P6 原入口 rolling/chaos 验收，也不能把可观测性 green 当作业务任务完成。

7. 过程控制

本规格不单独索引过程 issue；跨 L1 的内测、灰度和阶段活动索引统一保留在 PJ2026-01 HWLAB 总规格 的 7. 过程控制。