docs: specify v02 observability monitoring integration

2026-06-05 07:49:14 +08:00
parent 869746374b
commit 3ed0cdd773
3 changed files with 126 additions and 0 deletions
@@ -0,0 +1,124 @@
+# v0.2 Observability Monitoring 接入规格
+
+本文定义 HWLAB `v0.2` 接入 G14 共享 Prometheus 监控基础设施的应用侧规格。G14 监控基础设施本身由 UniDesk 长期参考 `docs/reference/g14-observability-infra.md` 管理；HWLAB 只声明业务服务如何暴露指标、如何被发现、如何查询和如何验收。
+
+## 在系统中的职责划分
+
+- G14 共享监控控制面运行在 `devops-infra` 平台基础设施 namespace，由 UniDesk/G14 基础设施规格管理。它承载 Prometheus Operator、Prometheus 实例、可选 Alertmanager/Grafana 以及跨 namespace scrape 选择策略。
+- `hwlab-v02` 只承载 HWLAB 业务服务、`/metrics` endpoint、Service labels/ports、`ServiceMonitor` / `PodMonitor` 和 `PrometheusRule`。不得把 Prometheus Operator、Prometheus、Grafana 或 Alertmanager 部署进 `hwlab-v02`。
+- `hwlab-g14-v02` Argo Application 仍只同步 `deploy/gitops/g14/runtime-v02` 到 `hwlab-v02`。监控控制面不能挂到这个 Application；它只消费业务 namespace 中的监控声明。
+- `hwlab-cli` 或 UniDesk 受控 CLI 可以作为查询入口，但必须通过 runtime namespace/lane 自动解析目标，不得手动暴露 Prometheus 公网地址。
+
+## 内部架构
+
+应用指标路径按 Kubernetes 原生监控模型收敛：
+
+```text
+hwlab-* service
+-> GET /metrics
+-> Service named port / labels
+-> ServiceMonitor in hwlab-v02
+-> Prometheus in devops-infra
+-> controlled CLI / proxy query
+```
+
+第一阶段优先使用 `ServiceMonitor`，因为 v0.2 保留服务均有 ClusterIP Service。动态 Job、AgentRun runner 或临时 debug Pod 的指标如需接入，后续使用 `PodMonitor`，但不得把 AgentRun runner 变成 HWLAB 自有运行面。
+
+所有 HWLAB `/metrics` endpoint 必须是内部指标入口，不参与公网 FRP 暴露。`hwlab-cloud-web` 和 `hwlab-edge-proxy` 不得把 `/metrics` 代理给普通浏览器或公网 API 调用方。Prometheus 抓取路径只允许从集群内 Service 访问。
+
+## API 接口说明
+
+### `/metrics`
+
+保留服务应逐步暴露 Prometheus 文本格式指标：
+
+| 服务 | 第一阶段指标 | 说明 |
+| --- | --- | --- |
+| `hwlab-cloud-api` | HTTP request count/latency、DB readiness/query latency、Code Agent submit/result/trace latency、AgentRun dispatch status、provider profile terminal status | 核心业务 authority，优先接入。 |
+| `hwlab-cloud-web` | HTTP request count/latency、static asset/proxy latency、upstream timeout/error count | 只记录同源代理与静态服务指标。 |
+| `hwlab-edge-proxy` | HTTP proxy request count/latency、upstream status、timeout/error count | 证明公网 edge 到 cloud-api 的性能。 |
+| `hwlab-device-pod` | executor request count/latency、job terminal status、gateway dispatch latency | 不记录 device output text。 |
+| `hwlab-agent-skills` | health/list/upload/tree/file request count/latency、error count | 技能包服务指标。 |
+| `hwlab-deepseek-proxy` | bridge request count/latency、upstream status、model/readiness probe result | 不记录 prompt、response 或 upstream token。 |
+
+指标命名使用稳定前缀 `hwlab_`。HTTP route 标签必须使用 route template，例如 `/v1/agent/chat/result/:traceId`，不得使用原始 URL。推荐基础标签：
+
+- `service`
+- `namespace`
+- `route`
+- `method`
+- `status_class`
+- `provider_profile`
+- `operation`
+- `terminal_status`
+
+禁止把这些值作为 label：
+
+- `traceId`
+- `sessionId`
+- `conversationId`
+- `threadId`
+- `runId`
+- `commandId`
+- `jobId`
+- 用户 ID、API key ID、prompt、assistant text、device output、SecretRef value
+
+这些高基数或敏感数据继续留在 trace/result/inspect、日志尾部或 issue 验收证据中，不进入 Prometheus label。
+
+### `ServiceMonitor`
+
+`deploy/gitops/g14/runtime-v02` 应生成或包含 v0.2 业务服务的 `ServiceMonitor`。Selector 必须同时约束：
+
+- namespace 为 `hwlab-v02`
+- `hwlab.pikastech.local/gitops-target=v02`
+- `hwlab.pikastech.local/monitoring=enabled`
+- 具体 `hwlab.pikastech.local/service-id`
+
+`ServiceMonitor` 不得选择 `hwlab-dev`、`hwlab-prod`、`agentrun-v01` 或任意无关 namespace。跨 namespace 抓取策略由 G14 共享 Prometheus 控制面决定，HWLAB 只提供带标签的声明。
+
+### `PrometheusRule`
+
+HWLAB v0.2 可声明 `PrometheusRule`，但规则只表达当前 v0.2 目标行为和性能观测，不作为新的发布 gate。第一阶段建议规则：
+
+- `hwlab-cloud-api` request p95/p99 latency。
+- Code Agent submit/result terminal latency。
+- AgentRun dispatch failure rate by provider profile。
+- edge-proxy upstream 5xx/timeout rate。
+- device-pod executor job failure rate。
+
+规则命名和 label 必须能定位 lane、namespace、service 和 operation；不要把单个 trace/run/job 写入规则。
+
+## 安全与暴露边界
+
+- `/metrics` 不需要经过公网 FRP；公网 `19666/19667` 不应返回 Prometheus 原始文本。
+- 如果未来给 `/metrics` 增加 bearer token，Secret 必须只记录 SecretRef 名称和 key，不能出现在文档、日志、issue 或 metric label 中。
+- Prometheus 读取 HWLAB 指标不等于拥有 HWLAB Secret、DB URL、provider key 或用户 API key 读取权限。
+- `hwlab-v02` 业务 namespace 不持有 Prometheus Operator 集群管理凭证，也不部署共享 Prometheus control-plane。
+
+## 测试规格
+
+## T1
+
+阅读本文和 UniDesk `docs/reference/g14-observability-infra.md`，然后用 CLI 手动测试以下内容：查询 G14 k3s 当前 CRD、namespace 和 `devops-infra` 对象，确认共享监控控制面如果存在则位于平台基础设施 namespace，不在 `hwlab-v02` 业务 service matrix 中。
+
+## T2
+
+阅读本文，然后用 CLI 手动测试以下内容：对每个已接入服务执行集群内 `GET /metrics`，确认 HTTP 200、Prometheus 文本格式、包含 `hwlab_` 前缀基础指标，且响应不包含 Secret、prompt、assistant text、device output 或高基数 ID。
+
+## T3
+
+阅读本文，然后用 CLI 手动测试以下内容：读取 `deploy/gitops/g14/runtime-v02` 或 live `hwlab-v02` 对象，确认 `ServiceMonitor` selector 限定 `hwlab-v02`、`gitops-target=v02`、`monitoring=enabled` 和具体 service id；确认不存在把 Prometheus、Grafana 或 Alertmanager 部署到 `hwlab-v02` 的对象。
+
+## T4
+
+阅读本文，然后用受控 CLI 或集群内查询测试以下内容：Prometheus 中 `up{namespace="hwlab-v02"}` 能看到已接入服务 target，基础延迟/错误率 PromQL 能返回结果，并确认公网 `http://74.48.78.17:19666/metrics` 和 `http://74.48.78.17:19667/metrics` 不暴露原始指标。
+
+## 规格的实现情况
+
+| 规格项 | 状态 | 说明 |
+| --- | --- | --- |
+| 应用侧监控接入边界 | 待实现 | 目标是 HWLAB 只负责 `/metrics`、ServiceMonitor/PrometheusRule 和 CLI 查询，不部署共享监控控制面。 |
+| G14 共享监控控制面 | 待实现 | 由 UniDesk/G14 基础设施规格定义，默认位于 `devops-infra`。 |
+| v0.2 服务 `/metrics` | 待实现 | 第一阶段优先 `hwlab-cloud-api`、`hwlab-cloud-web`、`hwlab-edge-proxy`、`hwlab-device-pod`、`hwlab-agent-skills`、`hwlab-deepseek-proxy`。 |
+| ServiceMonitor / PrometheusRule | 待实现 | 需要进入 v0.2 GitOps desired state，但不得变成发布旧门禁。 |
+| 受控查询与验收 | 待实现 | 需要通过 CLI/集群内查询证明 target discovered、query 可用和公网不暴露。 |
@@ -104,6 +104,7 @@ origin/v0.2
 | AgentRun v0.1 runner | 共享 Agent 执行基础设施 | 作为外部基础设施接入，不进 HWLAB service/artifact matrix | 否 | [agentrun-code-agent-dispatch.md](agentrun-code-agent-dispatch.md) |
 | `hwlab-agent-skills` wrapper | HWLAB 自研 bundle/health wrapper | 保留 | 仅常驻 wrapper 需要，P2 | [spec-v02-hwlab-agent-skills.md](spec-v02-hwlab-agent-skills.md) |
 | `hwlab-gateway` | HWLAB 自研用户端/硬件 transport | 保留 | 暂不迁 | [spec-v02-hwlab-gateway.md](spec-v02-hwlab-gateway.md)、[gateway-outbound-demo.md](gateway-outbound-demo.md) |
+| v0.2 Observability Monitoring | 应用侧监控声明 | 保留为业务接入能力，不进 runtime service inventory | 否 | [spec-v02-observability-monitoring.md](spec-v02-observability-monitoring.md) |
 | `hwlab-router` | HWLAB 自研路由占位服务 | 裁撤 | 否 | 本文即裁撤权威，不保留单独 spec |
 | `hwlab-tunnel-client` | HWLAB 自研 tunnel 状态占位服务 | 裁撤 | 否 | 本文即裁撤权威，不保留单独 spec |
 | `hwlab-gateway-simu` | HWLAB 自研模拟服务 | 裁撤 | 否 | 本文即裁撤权威，不保留单独 spec |