# PJ2026-010605 运维监控

## 修改历史

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

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

## 正文

## PJ2026-010605 运维监控需求规格

## 1. 文档控制

| 字段 | 内容 |
| --- | --- |
| 编号 | PJ2026-010605 |
| 短名 | 运维监控 |
| 层级 | L2 课题 |
| 状态 | 已生效 |
| 需求规格模板 | [ISO/IEC/IEEE 29148 需求规格模板](../../templates/iso-iec-ieee-29148-requirements-spec-template.md) |
| 上级规格 | [PJ2026-0106 平台运维](PJ2026-0106-platform-ops.md) |
| 规格治理索引 | [规格治理](spec-governance.md) |

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

## 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 的 active runner、stale lease、terminal report retry、reconciler backlog、projection lag 和 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性能](PJ2026-01060505-workbench-performance.md) | 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运维](PJ2026-010603-yaml-first-ops.md)、[Agent编排](PJ2026-0102-agent-orchestration.md)、[客户端](PJ2026-0104-client.md)、[用户管理](PJ2026-0105-user-management.md) |

运维监控应在 `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 目标架构图

```mermaid
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 数据流图

```mermaid
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 关键时序图

```mermaid
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运维](PJ2026-010603-yaml-first-ops.md)、[公开入口](PJ2026-010604-public-entry.md) |

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

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

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

| 编号 | 短名 | 主责模块 | 关联模块 |
| --- | --- | --- | --- |
| OPS-MON-REQ-003 | 运行摘要 | PJ2026-01060503 运行摘要 | [发布流水](PJ2026-010601-controlled-release.md)、[公开入口](PJ2026-010604-public-entry.md) |

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

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

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

| 编号 | 短名 | 主责模块 | 关联模块 |
| --- | --- | --- | --- |
| OPS-MON-REQ-004 | 边界约束 | PJ2026-01060504 边界约束 | [客户端](PJ2026-0104-client.md)、[Agent编排](PJ2026-0102-agent-orchestration.md)、[硬件池](PJ2026-0101-hardware-pool.md)、[HarnessRL](PJ2026-0103-harness-rl.md) |

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

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

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

| 编号 | 短名 | 主责模块 | 关联模块 |
| --- | --- | --- | --- |
| OPS-MON-REQ-005 | Workbench性能 | [PJ2026-01060505 Workbench性能](PJ2026-01060505-workbench-performance.md) | [Web工作台](PJ2026-010401-web-workbench.md)、[Agent编排](PJ2026-0102-agent-orchestration.md)、[API契约](PJ2026-010403-api-contract.md) |

运维监控应把 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性能](PJ2026-01060505-workbench-performance.md) 定义。

### 6.6 OPS-MON-REQ-006 Metrics 接入

| 编号 | 短名 | 主责模块 | 关联模块 |
| --- | --- | --- | --- |
| OPS-MON-REQ-006 | Metrics接入 | PJ2026-01060506 Metrics接入 | [YAML运维](PJ2026-010603-yaml-first-ops.md)、[发布流水](PJ2026-010601-controlled-release.md) |

运维监控应接入 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核心](PJ2026-010201-agentrun-core.md)、[HWLAB接入](PJ2026-010205-hwlab-dispatch.md)、[Workbench唯一投影](PJ2026-0104010803-workbench-unique-projection.md)、[AgentRun发布Lane](PJ2026-01060105-agentrun-v01-release-lane.md) |

运维监控应为 AgentRun/HWLAB rolling recovery 提供可查询的低基数 metrics、trace span 和受控 CLI 摘要。最小观测对象包括 active runner 数、runner job observation phase、stale lease 数、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 数、已恢复控制权数量、terminal report retry 数、projection lag 最大值、不可恢复 blocker 数和最近一次 reconciler 错误。该摘要只用于定位和发布判定，不替代 P6 原入口 rolling/chaos 验收，也不能把可观测性 green 当作业务任务完成。

## 7. 过程控制

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