feat: expose v02 webui performance metrics
This commit is contained in:
Codex Agent
@@ -99,6 +99,7 @@
|
||||
| `POST/GET/PATCH /v1/agent/sessions...` | 同源代理到 cloud-api 的显式 Code Agent session 生命周期入口；Web 不在普通 send 中隐式创建 session。 |
|
||||
| `POST /v1/agent/chat`、`POST /v1/agent/chat/steer`、`POST /v1/agent/chat/cancel` | 同源代理到 cloud-api 的 Code Agent 入口；steer 必须走同一个 `19666` Web path，由 cloud-api/AgentRun 判断目标 turn 是否可接收。 |
|
||||
| `POST /v1/device-pods/...` | 受控同源代理到 cloud-api 的 Device Pod job/操作入口；只要 Cloud API 已提供对应能力，Cloud Web 不能只代理 list/status 而让 job POST 在 `19666` 返回 404。 |
|
||||
| `POST /v1/web-performance` | 浏览器 RUM 上报入口；只允许低基数性能事件和数值，Cloud API 聚合后进入 Prometheus，详见 [spec-v02-observability-monitoring.md](spec-v02-observability-monitoring.md)。 |
|
||||
| `POST /v1/m3/io`、`POST /json-rpc` | 同源代理到受控 API；不能绕过 cloud-api 直连硬件服务。 |
|
||||
|
||||
## 测试规格
|
||||
@@ -109,6 +110,8 @@ Browser/layout/live smoke 属于显式专项诊断，不进入默认 Cloud Web c
|
||||
|
||||
临时 live DOM closeout probe 也必须使用 repo-owned 入口，不得在 `/tmp` 或 issue 验收脚本里手写 Playwright import/launch。标准入口是 `npm run web:dom-probe -- start --url http://74.48.78.17:19666/ --fresh-session`，它会从 workspace 解析依赖、复用统一 launcher、把 PID/stdout/stderr/result/screenshot 写入 `.state/web-live-dom-probe/`，并立即返回 `status` 短查询命令；`npm run web:dom-probe -- status <jobId>` 用于轮询结果。前端-only DOM/renderer/scroll 验收默认不提交 Code Agent；只有显式 `--message` 才经 UI 提交一条真实消息，并按默认策略尝试取消运行中的 turn。`npm run web:browser:guard` 是最小 grep guard，用于确认 `scripts/`、`tools/`、`web/` 下没有新增绕过 launcher 的直接 Chromium launch 调用，唯一允许文件是 `scripts/src/browser-launcher.mjs`。
|
||||
|
||||
WebUI 性能监控 issue 的 live closeout 不能只检查页面可见或 sidecar 存活；必须用 `19666` Web 入口触发真实浏览器 RUM 上报，再按 [spec-v02-observability-monitoring.md](spec-v02-observability-monitoring.md) 查询 `hwlab_webui_*` Prometheus 指标。LCP、Navigation Timing、业务 API timing、Long Task、CLS/INP/FID 近似只表达用户感知性能趋势，不替代 trace/result/inspect 的高基数排障证据。
|
||||
|
||||
Live smoke 登录前必须等待前端 auth bootstrap 结束（`body[data-auth-state]` 不再是 `checking`，且 login submit 已可见/可用）再填表；登录后必须断言 URL query 不含 `username` 或 `password`，防止原生 form submit 泄漏凭据并伪装成 layout 超时。
|
||||
|
||||
Workbench build summary 的顶部 chip 可以展示 `/v1/live-builds.latest`，但 `latest` 是跨所有 HWLAB runtime service 的最新构建，不是 Cloud Web 专属字段。Cloud Web 布局或 build-time issue 的验收必须打开详情或读取 `services[]` 中 `serviceId=hwlab-cloud-web` 的行，分别核对 build time、env image、actual commit、revision 和 source metadata；不得因为 `latest.serviceId` 指向 `hwlab-cloud-api` 就判定 Web 构建时间缺失。
|
||||
|
||||
@@ -30,6 +30,8 @@ hwlab-* service
|
||||
|
||||
sidecar 脚本通过 ConfigMap 挂载时，Deployment template 必须包含脚本内容 hash annotation。任何 metrics sidecar 脚本、目标 URL、端口或模板化配置变化都应触发 pod rollout；不能只更新 ConfigMap 后等待 kubelet 投影刷新，也不能把“Prometheus 能 scrape 到旧 sidecar”当成新逻辑已生效。
|
||||
|
||||
Cloud Web 用户感知性能必须进入同一套 Prometheus 查询面。浏览器侧 RUM 只上报低基数 route template、metric、method、status class、outcome 和数值，不上报 trace/session/conversation/thread/run/job/user ID 或正文。`hwlab-cloud-api` 负责接收 `/v1/web-performance`、做进程内聚合，并仅允许 `hwlab-cloud-api` pod 内 loopback 访问 `/v1/web-performance/metrics`；`hwlab-cloud-api` 的 metrics sidecar 再通过额外 loopback target 把 WebUI Prometheus 文本附加到 9100 `/metrics`。公网 `19666/19667` 仍不得暴露 Prometheus 原始文本。
|
||||
|
||||
## API 接口说明
|
||||
|
||||
### `/metrics`
|
||||
@@ -45,6 +47,14 @@ sidecar 脚本通过 ConfigMap 挂载时，Deployment template 必须包含脚
|
||||
| `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。 |
|
||||
|
||||
Cloud Web RUM 指标使用以下稳定前缀：
|
||||
|
||||
- `hwlab_webui_performance_sample_total`：Cloud API 接收并接受的浏览器性能样本计数。
|
||||
- `hwlab_webui_performance_duration_seconds`：Navigation Timing、LCP、INP/FID 近似、Long Task 和业务 API 请求耗时 histogram。
|
||||
- `hwlab_webui_layout_shift_score`：CLS histogram。
|
||||
|
||||
这些指标必须至少带 `service="hwlab-cloud-web"`、`namespace`、`gitops_target`、`kind`、`metric`、`route`、`method`、`status_class` 和 `outcome` 标签。`route` 必须是模板化路径，例如 `/v1/agent/chat/result/:id`，不能是原始 result/trace/session URL。
|
||||
|
||||
指标命名使用稳定前缀 `hwlab_`。HTTP route 标签必须使用 route template，例如 `/v1/agent/chat/result/:traceId`，不得使用原始 URL。推荐基础标签：
|
||||
|
||||
- `service`
|
||||
@@ -140,6 +150,10 @@ HWLAB v0.2 可声明 `PrometheusRule`，但规则只表达当前 v0.2 目标行
|
||||
|
||||
阅读本文，然后用 CLI 手动测试以下内容：检查已接入 pod 的容器状态，确认每个目标 pod 都包含 ready 的 `hwlab-metrics` sidecar 且 restartCount 没有异常增长。对 ConfigMap 承载的 sidecar 脚本或 render 模板做改动后，必须确认对应 Deployment 发生了新的 pod rollout。
|
||||
|
||||
## T7
|
||||
|
||||
阅读本文和 [spec-v02-hwlab-cloud-web.md](spec-v02-hwlab-cloud-web.md)，然后用真实浏览器或 repo-owned live DOM probe 访问 `http://74.48.78.17:19666/`，触发 Cloud Web 首屏和同源 API 请求；随后通过受控 Prometheus 查询确认 `hwlab_webui_performance_sample_total{namespace="hwlab-v02"}` 有样本，且 `histogram_quantile` 能基于 `hwlab_webui_performance_duration_seconds_bucket` 计算 LCP 或 `api_request` p95。若 sidecar 基础 target 正常但 WebUI 指标无样本，不能关闭 WebUI 性能监控 issue。
|
||||
|
||||
## 规格的实现情况
|
||||
|
||||
| 规格项 | 状态 | 说明 |
|
||||
@@ -149,3 +163,4 @@ HWLAB v0.2 可声明 `PrometheusRule`，但规则只表达当前 v0.2 目标行
|
||||
| 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；规则用于观测，不作为发布旧门禁。 |
|
||||
| 受控查询与验收 | 已实现 | 通过 UniDesk `hwlab g14 observability status|query` 和集群内边界检查验证 target discovered、health probe 可用和公网不暴露。 |
|
||||
| Cloud Web 用户感知性能 | 已实现 | 浏览器 RUM 经 `/v1/web-performance` 聚合为 `hwlab_webui_*` 指标，由 `hwlab-cloud-api` sidecar 附加导出，关闭 issue 前必须用 `19666` Web 入口触发并在 Prometheus 中看到样本。 |
|
||||
|
||||
Reference in New Issue
Block a user