docs(观测): 阶段四设计创始人评审通过定稿(§10 六项拍板回写)

创始人 2026-07-05 评审 §10 六项已拍:
- 告警件 Grafana 统一(替夜莺)· admin 一键进盘本期做 · traceId 并存关联 · 落点 mini-infra 32G
- new-api 冻结阀:本期只做通道巡检加告警,自动冻结阀排下一期
回写 §10 结论、§6/§7 内部一致(去评审前「待确认/待表态」措辞)、frontmatter status 转定稿。
docs-gate 七检全绿。

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

docs/agent-specs/2026-07-05-全链路可观测性-OTel三信号全栈-设计.md

@@ -1,8 +1,8 @@
 ---
 date: 2026-07-05
 topic: 观测体系-阶段四落地
-status: 草案(fable 主笔 · 双评审两轮:一轮 Codex+Opus REVISE→9+6 条已修、二轮 Opus REVISE→便宜档 OTLP 现状订正/脱敏验收判据/sot-impact 改动面 三条已修)· 方向 B 全栈 OTel、落点 mini-infra 加内存(创始人 2026-07-05 两拍)· 待创始人评审
-sot-impact: 修订两份 canonical,实施收口后同批回写。①《观测体系》(docs/architecture/运维/观测体系.md):**订正 §1 现状把 monitor starter 说成「classpath 上根本没有」的旧断言**(实为经 system/infra 传递在席、只是 actuator/micrometer optional 未装、SkyWalking Bean 注释掉 = 在席但残缺);补全五面落地与埋点清单;告警件由夜莺改 Grafana 统一,牵动其 §3.4 告警规则、§3.5 admin 告警概览 API、§5.1 验收多段(推翻件选型,待创始人确认);脱敏 processor 补进 §5.1 可跑验收;成功率告警阈值(80% 达标线与预警线)口径回写时统一;admin 一键进盘的本期/排期表态、new-api 冻结阀去留。②《k8s迁移》(docs/architecture/运维/k8s迁移.md,亦 canonical):落点从其规划的「mini-desktop 单节点 k3s observability namespace」反转为「mini-infra 扩内存后 docker-compose」——不止取代观测落点段,凡把观测栈算进 k3s 资源隔离的叙述(目标、拓扑、阶段规划、风险、验收各段)回写时逐段落地,免得留自相矛盾残句。两处改动面都以回写时对源核对为准。落点反转属横切一致性主人的灰色判断,已交创始人拍。
+status: 定稿(fable 主笔 · 双评审两轮修回:一轮 Codex+Opus 9+6 条、二轮 Opus 三条;创始人 2026-07-05 评审通过、§10 六项已拍)· 方向 B 全栈 OTel、落点 mini-infra 32G · 待实施(扩容窗口已过、可启动)
+sot-impact: 修订两份 canonical,实施收口后同批回写。①《观测体系》(docs/architecture/运维/观测体系.md):**订正 §1 现状把 monitor starter 说成「classpath 上根本没有」的旧断言**(实为经 system/infra 传递在席、只是 actuator/micrometer optional 未装、SkyWalking Bean 注释掉 = 在席但残缺);补全五面落地与埋点清单;告警件由夜莺改 Grafana 统一,牵动其 §3.4 告警规则、§3.5 admin 告警概览 API、§5.1 验收多段(推翻件选型,创始人 2026-07-05 已确认);脱敏 processor 补进 §5.1 可跑验收;成功率告警阈值(80% 达标线与预警线)口径回写时统一;admin 一键进盘拍定本期做、new-api 自动冻结阀拍定排下一期(本期只做通道巡检加告警)。②《k8s迁移》(docs/architecture/运维/k8s迁移.md,亦 canonical):落点从其规划的「mini-desktop 单节点 k3s observability namespace」反转为「mini-infra 扩内存后 docker-compose」——不止取代观测落点段,凡把观测栈算进 k3s 资源隔离的叙述(目标、拓扑、阶段规划、风险、验收各段)回写时逐段落地,免得留自相矛盾残句。两处改动面都以回写时对源核对为准。落点反转属横切一致性主人的灰色判断,已交创始人拍。
 上级: docs/architecture/运维/观测体系.md
 ---
 
@@ -103,12 +103,12 @@ flowchart LR
 | 缓存命中率 | Python worker | metric | `llm_cache_hit_rate`,cached token 导出 | 值有,需导出 |
 | 服务可用性 ≥99.5% | game-cloud + Collector | metric | OTel agent 自动出 HTTP server 指标 + actuator health | 需装 agent/actuator |
 | feed 首屏 P75<3s | game-studio 前端 | metric/RUM | 现有业务遥测埋点已在;OTel 前端观测排三期 | 业务 RUM 有 |
-| new-api 多通道健康 **+ 批跑冻结阀** | 后台巡检 job | metric **+ 控制动作** | 巡检探活每通道 + 查 key 额度;**可用通道掉到下限自动冻结后台批跑**(2026-06 通道整批作废的直接教训,巡检与冻结阀是一套) | 需新建;冻结阀本期与巡检一起做还是排后续,见 §10 |
+| new-api 多通道健康 **+ 批跑冻结阀** | 后台巡检 job | metric **+ 控制动作** | 巡检探活每通道 + 查 key 额度;**可用通道掉到下限自动冻结后台批跑**(2026-06 通道整批作废的直接教训,巡检与冻结阀是一套) | 需新建;**本期做通道巡检探活+健康指标/告警,自动冻结阀排下一期(§10.4 创始人拍)** |
 | 全链路 trace | 全链 | trace | Java agent + Python 三跳 traceparent(面四) | 便宜档主路写 jsonl 无 span、tier2 studio_sink 发 Studio 私有 root、Java 无 agent;三跳均未打通 |
 | 集中日志(脱敏后) | 全进程 | log | Collector filelog / logback OTLP,trace_id 注入 MDC,只收 WARN/ERROR;**进库前经脱敏 processor** | 需新建 |
 | 脱敏 processor | Collector | 安全红线 | 手机号/token 进 Tempo/Loki 前最后一道,继承《观测体系》§3.1/§5.2 | **必做,不能丢** |
 | SAA 图节点 span | game-cloud aigc | trace | 装 micrometer 即活,**但仅 dispatcher=saa 的 opt-in 进程内路有效;默认 http 路生成不跑 SAA 图、其 trace 来自 Python 线** | 依赖就位,限定路 |
-| admin 一键进盘 | Grafana | 运维入口 | 《观测体系》§2/§3.5 列为硬目标;本设计明确本期做还是排期,见 §10 | 待表态 |
+| admin 一键进盘 | Grafana | 运维入口 | 《观测体系》§2/§3.5 硬目标,本期落 | **本期做(§10.3 创始人拍)** |
 
 ## 7. 关键取舍
 
@@ -116,7 +116,7 @@ flowchart LR
 
 **game-cloud 用 OTel Java agent 为主、micrometer bridge 收编存量。** 一个参数拿全链、顺手把 SAA observation 和半死的 SkyWalking 收敛成一条 OTel。
 
-**告警件用 Grafana 统一告警,替下原稿的夜莺 Nightingale。** 这是相对《观测体系》原稿的一处实质改动:既然看板已统一在 Grafana,再引夜莺会多一套要维护的组件和一份要对齐的规则,而 Grafana 自带告警规则加飞书/钉钉 webhook 已够覆盖 MVP 的阈值告警,少一个常驻件也少吃一份内存。夜莺的优势在大规模多租户告警治理,MVP 用不上。**此项推翻原 canonical 的件选型,请创始人在评审时确认。**
+**告警件用 Grafana 统一告警,替下原稿的夜莺 Nightingale。** 这是相对《观测体系》原稿的一处实质改动:既然看板已统一在 Grafana,再引夜莺会多一套要维护的组件和一份要对齐的规则,而 Grafana 自带告警规则加飞书/钉钉 webhook 已够覆盖 MVP 的阈值告警,少一个常驻件也少吃一份内存。夜莺的优势在大规模多租户告警治理,MVP 用不上。**此项推翻原 canonical 的件选型,创始人 2026-07-05 评审已确认(§10.1),回写《观测体系》时落。**
 
 **成本指标的权威级别是降级的,要认。** 本期的 `llm_cost` 是 worker 自估值,不是 new-api 的实际计费流水;便宜档小于 ¥10、tier2 小于 ¥50 是硬预算,缓存漂移会让成本翻几倍,靠自估值做告警在 token 口径或倍率漂移时可能真花超了不报。所以本期标清「估值非权威」、留 `logs.quota` 对账薄片作 follow-up、告警阈值留余量。
 
@@ -142,11 +142,11 @@ flowchart LR
 
 内存不是唯一的风险,CPU 和 IO 争用同样真:观测栈和 new-api 同箱,失控的 Prometheus/Tempo 可能在 CPU/IO 上压到生成命脉,所以每个观测容器的内存和 CPU 双上限、进程优先级低于生产件是上线即设、不留口子。第二个风险是 agent 注入对 game-cloud 启动和性能的影响,缓解是先在 staging 挂 agent 验启动加压一轮时延对比,确认开销可接受再上生产 profile(验收第 6 条兜)。第三是脱敏——trace 属性和日志正文里有用户内容,脱敏 processor 漏配就是安全回退,所以它是必做项、进验收。回滚极干净:观测是纯增量的旁路,回滚等于摘掉 agent 参数、关掉 Python 的 OTLP 地址、停观测栈 compose、按存储治理的删除策略清 MinIO bucket,主链和业务代码一行不受影响。
 
-## 10. 待创始人评审确认项
+## 10. 创始人评审结论(2026-07-05 六项已拍)
 
-1. **告警件用 Grafana 统一告警替下夜莺**(§7)——推翻《观测体系》canonical 的件选型。
-2. **落点反转同批改两份 canonical**——《观测体系》和《k8s迁移》都要回写,后者的 mini-desktop k3s observability 落点被本设计取代;这属横切一致性主人的判断,确认后两份同批改。
-3. **admin 一键进盘本期做还是排期**——《观测体系》§2 的硬目标,别让它在「五面」里蒸发成孤儿。
-4. **new-api 批跑冻结阀本期做还是排期**——命脉级控制,2026-06 通道作废的教训沉淀,建议连巡检一起做。
-5. **业务 traceId 与 W3C traceId 采并存关联**(§5 面四)——影响排障时 trace 的连续性。
+1. **告警件用 Grafana 统一告警替下夜莺**(§7)——**✅ 拍定 Grafana 统一**。看板已在 Grafana、自带告警规则加飞书/钉钉 webhook 已够覆盖 MVP 阈值告警、少一套常驻件;推翻《观测体系》canonical 的夜莺件选型,回写时落。
+2. **落点反转同批改两份 canonical**——**✅ 落点 mini-infra 加内存(07-05 已两拍)**。《观测体系》和《k8s迁移》回写是实施收口的执行动作,后者规划的 mini-desktop k3s observability 落点被本设计取代;属横切一致性主人的判断,随实施同批改。
+3. **admin 一键进盘本期做还是排期**——**✅ 本期做**。《观测体系》§2 的硬目标,顺阶段四一起落,不让它在「五面」里蒸发成孤儿。
+4. **new-api 批跑冻结阀本期做还是排期**——**✅ 本期只做通道健康巡检加告警,自动冻结阀排下一期**。命脉级的自动控制动作暂缓,本期先把通道可用性指标和告警这双眼睛装上;冻结阀作为已登记的 follow-up 保留,2026-06 通道整批作废的教训不丢。
+5. **业务 traceId 与 W3C traceId 采并存关联**(§5 面四)——**✅ 并存关联**。业务 traceId 作 span 属性保留(承担产物归位和回调关联),W3C traceparent 负责跨语言贯穿,不强升业务 traceId 的格式。
 6. **mini-infra 扩容目标规格**——已实测坐实(2026-07-05 关机前):15G 机、空闲仅 427Mi、available 7.3G 全是可回收缓存、容器实占约 7.5G(ragflow 独占 3.35G 最大且 AI 件爱涨)、swap 4G 基本未用。观测栈带内存和 CPU 双上限约 3 到 4G 常驻。**建议扩到 32G(下限:常驻约 11.5G 加约 20G 缓存与 spike 余量,干净解决 OOM)或 64G(一台管到底,给 ragflow 与生成负载的长期涨幅留头)**。**✅ 已扩容并复验(2026-07-05):创始人选 32G,mini-infra 从 15G 升到 31Gi 可用**,复验整栈健康——used 6.7Gi、free 20Gi、**available 24Gi**(扩前仅 427Mi),12 容器全回来零异常退出(minio/mysql/postgres/redis/nginx/new-api 均 healthy),Nacos readiness 200。观测栈 3 到 4G 常驻装进 24Gi 余量绰绰有余、OOM 风险解除。本项收口:实施落 mini-infra、内存维度已备;CPU/IO 隔离纪律(§5 面三、§9)与跨机拓扑仍按设计执行。