From 3ed0cdd77351450a20dbc1cd00c81b1ab81dbed0 Mon Sep 17 00:00:00 2001 From: Codex Agent Date: Fri, 5 Jun 2026 07:49:14 +0800 Subject: [PATCH] docs: specify v02 observability monitoring integration --- AGENTS.md | 1 + .../spec-v02-observability-monitoring.md | 124 ++++++++++++++++++ docs/reference/spec-v02-services.md | 1 + 3 files changed, 126 insertions(+) create mode 100644 docs/reference/spec-v02-observability-monitoring.md diff --git a/AGENTS.md b/AGENTS.md index a34cd006..8984711a 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -81,6 +81,7 @@ HWLAB 是硬件实验室运行面和控制面项目。本文是 agent、指挥 - v0.2 `hwlab-device-pod` 部署服务规格：[docs/reference/spec-v02-hwlab-device-pod-service.md](docs/reference/spec-v02-hwlab-device-pod-service.md)。 - v0.2 `hwlab-gateway` 硬件 transport 边界规格：[docs/reference/spec-v02-hwlab-gateway.md](docs/reference/spec-v02-hwlab-gateway.md)。 - v0.2 `hwlab-edge-proxy` API edge proxy 规格：[docs/reference/spec-v02-hwlab-edge-proxy.md](docs/reference/spec-v02-hwlab-edge-proxy.md)。 +- v0.2 Observability Monitoring 接入规格，应用侧 `/metrics`、ServiceMonitor、PrometheusRule 和 G14 共享监控边界：[docs/reference/spec-v02-observability-monitoring.md](docs/reference/spec-v02-observability-monitoring.md)。 - v0.2 Postgres 稳定外部服务规格：[docs/reference/spec-v02-postgres.md](docs/reference/spec-v02-postgres.md)。 - v0.2 Codex API Forwarder/hyueapi 稳定外部通道规格：[docs/reference/spec-v02-codex-api-forwarder.md](docs/reference/spec-v02-codex-api-forwarder.md)。 - v0.2 DeepSeek/Moon Bridge 稳定外部服务规格：[docs/reference/spec-v02-deepseek-proxy.md](docs/reference/spec-v02-deepseek-proxy.md)。 diff --git a/docs/reference/spec-v02-observability-monitoring.md b/docs/reference/spec-v02-observability-monitoring.md new file mode 100644 index 00000000..3df4bc33 --- /dev/null +++ b/docs/reference/spec-v02-observability-monitoring.md @@ -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 可用和公网不暴露。 | diff --git a/docs/reference/spec-v02-services.md b/docs/reference/spec-v02-services.md index 80a09d34..77c51c2b 100644 --- a/docs/reference/spec-v02-services.md +++ b/docs/reference/spec-v02-services.md @@ -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 |