feat: add platform observability tracing CLI

config/platform-infra/observability.yaml

@@ -0,0 +1,122 @@
+version: 1
+kind: platform-infra-observability
+
+metadata:
+  id: observability
+  owner: unidesk
+  spec: PJ2026-01060501 OTel追踪 draft-2026-06-19-p0
+  relatedIssues:
+    - 489
+
+defaults:
+  targetId: D601
+
+images:
+  collector:
+    repository: otel/opentelemetry-collector-contrib
+    tag: 0.130.1
+    pullPolicy: IfNotPresent
+  tempo:
+    repository: grafana/tempo
+    tag: 2.8.1
+    pullPolicy: IfNotPresent
+
+targets:
+  - id: D601
+    route: D601:k3s
+    namespace: platform-infra
+    role: active
+    enabled: true
+    createNamespace: true
+
+collector:
+  deploymentName: otel-collector
+  serviceName: otel-collector
+  configMapName: otel-collector-config
+  replicas: 1
+  healthPort: 13133
+  otlp:
+    grpcPort: 4317
+    httpPort: 4318
+
+traceBackend:
+  type: tempo
+  deploymentName: tempo
+  serviceName: tempo
+  configMapName: tempo-config
+  replicas: 1
+  httpPort: 3200
+  otlp:
+    grpcPort: 4317
+    httpPort: 4318
+  storage:
+    mode: emptyDir
+    retention: 24h
+
+sampling:
+  mode: parentbased_traceidratio
+  ratio: 1
+
+instrumentation:
+  contextPropagation:
+    - tracecontext
+    - baggage
+  serviceConnections:
+    - serviceName: hwlab-cloud-api
+      owningRepo: pikasTech/HWLAB
+      targetNode: D601
+      lane: v0.3
+      namespace: hwlab-v03
+      requiredSpans:
+        - POST /v1/agent/chat
+        - durable_admission
+        - billing_preflight
+        - agentrun_dispatch
+        - projection_write
+        - trace_events_read
+        - turn_status_read
+    - serviceName: user-billing
+      owningRepo: pikasTech/HWLAB
+      targetNode: D601
+      lane: v0.3
+      namespace: hwlab-v03
+      requiredSpans:
+        - billing_preflight
+    - serviceName: agentrun-manager
+      owningRepo: pikasTech/agentrun
+      targetNode: D601
+      lane: v0.2
+      namespace: agentrun-v02
+      requiredSpans:
+        - agentrun_dispatch
+        - run_created
+        - command_result
+        - projection_sync
+
+resourceAttributes:
+  required:
+    - service.name
+    - deployment.environment
+    - unidesk.node
+    - hwlab.lane
+    - k8s.namespace.name
+    - git.commit
+  businessCorrelationAttributes:
+    - traceId
+    - sessionId
+    - turnId
+    - runId
+    - commandId
+
+probes:
+  readinessPath: /ready
+  traceQueryPathTemplate: /api/traces/{{traceId}}
+  statusEndpoints:
+    - name: tempo-ready
+      service: tempo
+      portName: http
+      path: /ready
+    - name: collector-health
+      service: otel-collector
+      portName: health
+      path: /

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

@@ -23,30 +23,32 @@
 | 上级规格 | [PJ2026-0106 平台运维](PJ2026-0106-platform-ops.md) |
 | 规格治理索引 | [规格治理](spec-governance.md) |
 
-本文采用 ISO/IEC/IEEE 29148 需求规格模板的项目裁剪版：正文只保留 HWLAB Prometheus 运维监控的稳定使命、范围、术语、系统边界、内部分工和原子需求。Workbench 用户可感知性能监控的架构图、数据流图、时序图和实现引用要求由 [PJ2026-01060505 Workbench性能](PJ2026-01060505-workbench-performance.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 和配套状态查询入口采集 HWLAB 运行面 metrics、scrape target、alert rule、服务健康指标和资源指标，使平台运维能够发现服务不可用、入口漂移、资源异常和发布后运行状态退化。
+运维监控负责通过 Prometheus 和 OpenTelemetry 的分工协作采集 HWLAB 运行面 metrics、scrape target、alert rule、服务健康指标、资源指标和关键请求 trace，使平台运维能够发现服务不可用、入口漂移、资源异常、发布后运行状态退化，以及单个 Workbench/AgentRun 请求在 admission、billing、dispatch、projection 或 replay 阶段的失败位置。
 
-本课题的目标状态是：各业务 L1 提供自己的服务健康和业务状态指标，平台运维统一接入 Prometheus 并输出可查询、可告警、可回溯的运维状态；监控只判断运行面健康和资源状态，不替代业务成功标准。
+本课题的目标状态是：各业务 L1 提供自己的服务健康、业务状态指标和关键链路 trace 语义，平台运维统一接入 Prometheus metrics 面和 OpenTelemetry tracing 面并输出可查询、可告警、可回溯的运维状态；监控只判断运行面健康、资源状态和单次请求因果链，不替代业务成功标准。
 
-运维监控接入必须遵循 UniDesk YAML-first ops：scrape target、alert rule、recording rule、summary query、target/node/lane、namespace、endpoint、采样/保留/阈值等 UniDesk 自有运维事实必须归属 YAML；受控 CLI 负责读取、校验、渲染、apply/status/summary。运行面对象和 Prometheus 查询结果只作为观测证据，不反推为配置真相。
+运维监控接入必须遵循 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 状态摘要。
-- 监控数据的受控查询、低噪声摘要、失败归因和敏感输出约束。
+- 监控和 trace 数据的受控查询、低噪声摘要、失败归因和敏感输出约束。
 
 ### 2.3 范围外
 
 - Agent command、CaseRun、HWPOD operation 或用户账本的业务成功标准由对应 L1 定义。
-- 长 trace、原始日志、测试报告、截图、CaseRun registry 和用户反馈正文不进入本规格。
+- 完整 prompt、assistant 正文、tool 参数、命令输出、原始日志、测试报告、截图、CaseRun registry 和用户反馈正文不进入本规格或默认 trace attribute。
 - Prometheus 具体阈值、保留周期、告警路由、采样间隔和容量数值以 YAML/config 为准，不在本规格硬编码。
+- OpenTelemetry Collector image、trace backend image、存储模式、retention、采样率、endpoint 和服务接入关系以 YAML/config 为准，不在业务代码硬编码。
 - 监控告警不能代替发布流水、业务验证、CaseRun 评价或用户反馈分流。
 
 ## 3. 术语表
@@ -54,6 +56,10 @@
 | 术语 | 定义 |
 | --- | --- |
 | Prometheus 运维监控 | 通过 Prometheus 采集、查询和告警 HWLAB 运行面 metrics 的运维能力。 |
+| OpenTelemetry tracing | 通过 OTel Collector、trace backend、span 和 W3C trace context 关联单次请求跨服务因果链路的运维能力。 |
+| trace backend | 保存并查询 trace/span 的平台组件，首期可由 Tempo 或 Jaeger 承担，部署事实由 YAML 控制。 |
+| 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 渲染和验证的运维形态。 |
 | scrape target | Prometheus 抓取 metrics 的目标服务、path 和 label 集合。 |
@@ -67,33 +73,119 @@
 | 边界项 | 内容 |
 | --- | --- |
 | 外部使用者 | 平台管理员、发布操作人员、值守自动化、需要运行状态的各 L1 owner。 |
-| 外部输入 | 服务 metrics endpoint、health/readiness、runtime resource 指标、scrape 配置、alert rule 配置和查询请求。 |
-| 受控资源 | Prometheus target、metrics、alert rule、运行面状态摘要、服务健康指标和资源指标。 |
-| 外部输出 | target 状态、metrics 查询结果、alert 状态、运行健康摘要、入口健康摘要和 redacted 失败原因。 |
-| 用户接口 | Prometheus 查询、受控平台运维 CLI、发布状态摘要和各 L1 health/status 页面或命令。 |
-| 系统边界 | 运维监控负责运行面可观察和告警；不定义业务完成标准，不保存长证据，不把监控 green 当作业务通过。 |
+| 外部输入 | 服务 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 查询结果、运行健康摘要、入口健康摘要和 redacted 失败阶段。 |
+| 用户接口 | Prometheus 查询、OpenTelemetry trace 查询、受控平台运维 CLI、发布状态摘要和各 L1 health/status 页面或命令。 |
+| 系统边界 | 运维监控负责运行面可观察、告警和单次请求因果链；不定义业务完成标准，不保存默认长证据，不把监控 green 或 trace 可查当作业务通过。 |
 
 ## 5. 内部分工与规格索引
 
 | 编号 | 模块或课题 | 规格文档 | 主责边界 | 上游依赖 | 下游支撑 |
 | --- | --- | --- | --- | --- | --- |
-| PJ2026-01060501 | Metrics接入 | 本规格 6.1 | metrics endpoint、scrape target 和 label 口径 | 各 L1 服务健康指标 | Prometheus 查询 |
+| 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 查询 |
 
 ## 6. 原子需求
 
-### 6.1 OPS-MON-REQ-001 Metrics 接入
+### 6.1 OPS-MON-REQ-001 OTel 追踪
 
 | 编号 | 短名 | 主责模块 | 关联模块 |
 | --- | --- | --- | --- |
-| OPS-MON-REQ-001 | Metrics接入 | PJ2026-01060501 Metrics接入 | [YAML运维](PJ2026-010603-yaml-first-ops.md)、[发布流水](PJ2026-010601-controlled-release.md) |
+| 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) |
 
-运维监控应接入 HWLAB 各运行服务的 metrics endpoint 和 scrape target，使服务 live、ready、resource、queue、error、latency 和依赖健康可以被 Prometheus 查询。
+运维监控应在 `platform-infra` 提供 YAML-first OpenTelemetry tracing 能力，使一次 Workbench submit 或等价 API 请求可以沿 Cloud API admission、billing preflight、AgentRun dispatch、projection write、trace events read 和 Web replay 等阶段保留可查询 span。
 
-各 L1 负责定义自身服务健康指标含义；平台运维负责通过 YAML-first UniDesk ops 统一接入、命名、label 和可查询状态。metrics 缺失应暴露为监控缺口，不得用日志 grep、一次性 curl、手工 `kubectl apply` 或人工截图替代长期监控。
+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、endpoint、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。
+
+首期应用侧手工 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。
+
+#### 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 告警规则
 
@@ -135,6 +227,16 @@
 
 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` 或人工截图替代长期监控。
+
 ## 7. 过程控制
 
 本规格不单独索引过程 issue；跨 L1 的内测、灰度和阶段活动索引统一保留在 [PJ2026-01 HWLAB 总规格](PJ2026-01-HWLAB.md) 的 `7. 过程控制`。

scripts/src/platform-infra.ts

@@ -262,7 +262,7 @@ interface ManagedResourceCleanupPlan {
 export function platformInfraHelp(): unknown {
   const target = sub2ApiHelpTargetSummary();
   return {
-    command: "platform-infra sub2api|langbot|n8n|wechat-archive ...",
+    command: "platform-infra sub2api|langbot|n8n|wechat-archive|observability ...",
     output: "json",
     usage: [
       "bun scripts/cli.ts platform-infra sub2api plan [--target G14|D601]",
@@ -297,8 +297,14 @@ export function platformInfraHelp(): unknown {
       "bun scripts/cli.ts platform-infra wechat-archive collector-image-build --confirm",
       "bun scripts/cli.ts platform-infra wechat-archive collector-apply --confirm",
       "bun scripts/cli.ts platform-infra wechat-archive collector-status --full",
+      "bun scripts/cli.ts platform-infra observability plan --target D601",
+      "bun scripts/cli.ts platform-infra observability apply --target D601 --dry-run",
+      "bun scripts/cli.ts platform-infra observability apply --target D601 --confirm",
+      "bun scripts/cli.ts platform-infra observability status --target D601",
+      "bun scripts/cli.ts platform-infra observability validate --target D601",
+      "bun scripts/cli.ts platform-infra observability trace --target D601 --trace-id <traceId>",
     ],
-    description: "Operate YAML-controlled platform-infra services such as Sub2API, LangBot, n8n and WeChat archive workflows. Public services use PK01 Caddy+FRP rather than Kubernetes Ingress, NodePort, or LoadBalancer.",
+    description: "Operate YAML-controlled platform-infra services such as Sub2API, LangBot, n8n, WeChat archive workflows and OpenTelemetry tracing. Public services use PK01 Caddy+FRP rather than Kubernetes Ingress, NodePort, or LoadBalancer.",
     target,
     codexPool: {
       usage: [
@@ -341,6 +347,10 @@ export async function runPlatformInfraCommand(config: UniDeskConfig, args: strin
     const { runWechatArchiveCommand } = await import("./platform-infra-wechat-archive");
     return await runWechatArchiveCommand(config, args.slice(1));
   }
+  if (target === "observability") {
+    const { runPlatformObservabilityCommand } = await import("./platform-infra-observability");
+    return await runPlatformObservabilityCommand(config, args.slice(1));
+  }
   if (target !== "sub2api") return unsupported(args);
   if (action === "plan" || action === undefined) return plan(parseTargetOptions(args.slice(2)));
   if (action === "apply") return await apply(config, parseApplyOptions(args.slice(2)));