Monitoring dashboard

Monitoring dashboard 表示一套面向长期运行服务的观测集成：应用从真实 source event 产出有界、低基数的 Counter、Gauge 和 Histogram，Prometheus 负责抓取与时间序列历史，Grafana 通过仓库内 provisioning 提供固定 dashboard、查询和告警；Docker Compose 或等价编排负责把应用 exporter、Prometheus、Grafana 以及可选 trace backend 放进明确的网络、存储和凭据边界。它回答的是“服务现在是否健康、慢在哪里、等待/重试/资源竞争怎样变化”，不是单纯把日志画成图。

这个 Topic 不把指标历史当作业务事实，不用 Prometheus 取代业务数据库，也不把 Grafana UI、常驻 profiler、原始 SQL/请求身份或无限 label 集合当作默认观测面。request tracing、hotpath 归因和按需 CPU profile 是可以叠加的诊断能力，但不自动成为必选项、业务成功条件或固定容量/留存方案（projects/codex-vibe-monitor.md、docs/design/performance-observability.md）。

当服务需要跨时间查看请求延迟、错误/取消、重试、队列或数据库等待、资源趋势，且希望把 exporter、Prometheus、Grafana dashboard/alert 作为可复现的部署和审查合同管理时使用。若任务还需要回答“某一条请求经历了哪些阶段”，再把 tracing 作为独立的可选扩展；若需要回答“哪个函数或规范化 SQL 归因”，再考虑 hotpath；若需要短时 CPU 调查，再使用受限的按需 profiler。

如果项目只有一次性本地日志、静态构建图、少量健康检查，或 dashboard 仅由人工在 Grafana UI 中维护而没有稳定的 provisioning/查询合同，不应命中本 Topic。若变更只涉及业务报表或单次调用明细，也应优先使用业务持久化/应用报表相关 Topic，而不是把业务事实塞入 metrics。

• 先定观测边界，再选工具。 以真实事件定义指标语义，区分 Counter reset、Gauge 水位、classic Histogram 与 native Histogram；把请求头、完整 body、upstream attempt、重试、队列等待、SQL 执行和 ACK 等不同生命周期分开，避免用一个“总耗时”掩盖根因（projects/codex-vibe-monitor.md、docs/specs/performance-telemetry/METRICS.md）。
• 默认有界且低基数。 对 route、phase、status class、outcome、task key 等 label 使用显式 allowlist，禁止用户、账号、IP、request ID、conversation、原始 URL、SQL 参数及其 hash 进入 label；动态条目需要运行时上限，展示层 limit 不能代替采集侧限额（docs/design/performance-observability.md）。
• 分开组件职责。 应用 exporter 负责业务运行时的聚合指标，hotpath exporter 负责函数/规范化 SQL/支持的锁归因，Prometheus 负责历史，Grafana 负责查询/展示/规则，业务数据库继续保存业务事实。Grafana dashboard、datasource、recording rule 和 alert rule 应由仓库 provisioning 管理，避免 UI 修改漂移（ops/observability/prometheus.yml、ops/observability/grafana/provisioning/）。
• 把 Compose 当部署合同。 为应用、monitoring backend 和可选 tracing backend 设计明确的网络成员资格、named volume、只读配置挂载和必要的 host exposure；Prometheus/Tempo 不应因为方便调试而直接公网暴露，监控入口、scrape、report、Viewer 和 tracing 摄入/查询凭据应分离（ops/observability/compose.yml、ops/observability/README.md）。
• 联合验证健康与数据质量。 验证 target up、scrape error、freshness、样本数、Counter reset、低样本分位数和 dashboard query 语义；up == 1 只说明抓取进程可达，不等于业务有足够流量或结果可信。还要验证 Prometheus/Grafana/exporter/report/sampler 停止时业务请求、ACK、任务和持久化仍能完成（scripts/cvm-observe、docs/specs/performance-telemetry/SPEC.md）。
• 把 tracing 当可选升级路径。 只有聚合 metrics 无法定位单请求阶段时才加入 tracing；默认可关闭、异步、有界、独立凭据和 tenant/network，限制 trace 属性、窗口、结果和查询并发，并把缺测/截断/丢弃显式显示为未知或降级。tracing 不替代 metrics，也不应成为业务健康依赖（src/observability/traces.rs、docs/design/request-lifecycle-observability.md）。
• Profiler 走按需、受限入口。 CPU profile 和 hotpath report 用固定白名单、独立只读身份、超时/大小/频率上限；禁止开放任意 PID、任意路径、shell 或常驻 profiler daemon。项目具体端口、留存、采样率、容量和性能预算必须回到项目自己的合同与验证证据，不能复制本 Topic 的代表实现数字（scripts/cvm-hotpath-cpu、scripts/cvm-observe）。

• projects/codex-vibe-monitor.md：完整的服务观测样本，展示有界应用 metrics、Prometheus/Grafana Compose、六个 dashboard、hotpath-rs、受限 CPU profile，以及默认关闭的 Tempo/request tracing 如何与业务 SQLite 分工；其中项目数字和网络细节只作为该项目事实。
• ops/observability/compose.yml、ops/observability/prometheus.yml：展示 Compose 服务、网络/volume、scrape target、协议和 allowlist 如何进入 checked-in 配置。
• ops/observability/grafana/provisioning/、ops/observability/grafana/dashboards/cvm-*.json：展示 datasource、dashboard provider、alert rule 和六个固定 dashboard 的文件化交付面。
• src/observability/：展示应用侧 recorder、请求/body/browser 采集、资源 sampler、报告适配和 tracing 状态如何保持有界并与业务成功语义隔离。
• scripts/cvm-observe、scripts/cvm-hotpath-cpu：展示机器查询与按需 CPU 诊断如何使用 HTTPS/独立 token 和受限参数；它们是参考边界，不是所有项目必须复制的命令行界面。
• docs/solutions/performance/prometheus-grafana-compose-integration.md：提供该集成的来源 solution，供回读职责、验证顺序和已知误区；本 Topic 只提炼跨项目模式，不复制其部署实例。

• 把项目数字写成通用默认值。 直接复制某项目的端口、retention、sampling、dashboard 数量或性能预算，会在不同流量/容量/合规边界下失真；应只复用职责、边界和验证方法，并让目标项目单独定量验证（projects/codex-vibe-monitor.md）。
• 高基数或敏感标签泄漏。 把用户、账号、IP、request ID、原始 URL 或 SQL 参数写进 metrics 会造成成本和隐私风险；使用固定枚举、规范化 SQL、动态条目上限和摘要/拒绝计数（docs/design/performance-observability.md）。
• 混淆 Histogram 语义。 用 native Histogram 查询 classic bucket，或把 le 留在错误的聚合中，会得到空图或错误分位数；在 exporter、PromQL、dashboard 和 recording rule 中保持同一协议与标签语义（ops/observability/prometheus.yml、ops/observability/grafana/dashboards/）。
• 用 up 代替观测质量。 target 可达但业务没有样本、scrape stale 或查询窗口低样本时，不能把空结果当作零；联合检查 freshness、样本量、错误和 reset，并明确 unknown/degraded（scripts/cvm-observe）。
• 把监控入口当业务入口。 公网暴露 Prometheus、复用 scrape/read/Viewer/OTLP 凭据，或让 Grafana/Tempo 查询直达内部 backend，会扩大攻击面；分离身份、私网抓取、固定入口和只读权限，拒绝重定向与租户伪造（ops/observability/compose.yml、ops/observability/README.md）。
• Grafana UI 漂移配置真相。 只在 UI 中编辑 dashboard 或 alert 会使 Compose、代码审查和恢复不可重复；用 file provisioning、固定 UID、只读 provider 和仓库内 JSON/YAML 作为真相，平台通知 contact point 仍由平台管理（ops/observability/grafana/provisioning/）。
• 观测反向阻塞业务。 让 exporter、trace export、报告读取或 profiler attach 同步等待外部系统，会把监控故障变成请求/ACK/写入故障；使用异步有界管线、超时、丢弃/降级计数，并把观测状态与业务成功解耦（docs/specs/performance-telemetry/SPEC.md）。
• 把 tracing 或 profiler 变成无界常驻面。 默认开启完整 trace、开放任意 profile target 或把 trace backend 当健康依赖，会增加开销和权限风险；tracing 采用显式 opt-in，profiler 采用固定受限命令，容量和开销结论另行验收（src/observability/traces.rs、scripts/cvm-hotpath-cpu）。

• projects/codex-vibe-monitor.md
• ops/observability/README.md
• ops/observability/compose.yml
• ops/observability/prometheus.yml
• ops/observability/recording-rules.yml
• ops/observability/grafana/dashboards/
• ops/observability/grafana/provisioning/
• src/observability/
• scripts/cvm-observe
• scripts/cvm-hotpath-cpu
• docs/design/performance-observability.md
• docs/design/request-lifecycle-observability.md
• docs/specs/performance-telemetry/SPEC.md
• docs/specs/performance-telemetry/METRICS.md
• docs/solutions/performance/prometheus-grafana-compose-integration.md