05-EFT.WP.Core.Errors v1.0 | 第6章 记录、追踪与诊断

目录 ／ 文档-技术白皮书 ／ 05-EFT.WP.Core.Errors v1.0

第6章 记录、追踪与诊断

I. 目标与范围

• 目标：定义从错误发生到根因定位的统一记录与追踪体系，确保事件可重放、证据可核验、诊断可量化，并与 I50 6—log_event、traceback_summary、attach_traceability 对齐。
• 范围：覆盖模型残差 r、误差预算 EB、到达时量 T_arr = ( ∫_gamma ( n_eff / c_ref ) d ell ) 的全链路证据化与跨卷绑定。

II. 公设（记录与追踪）

• P76-1（事件原子性）：日志事件以最小可判定单元记录，不得拼接跨阶段信息；跨阶段关系由 trace_id 与 span_id 表示。
• P76-2（证据可再现）：每一诊断结论必须可由记录的 data_fingerprint、code_fingerprint、unit_policy、RefCond、theta 重放得到同分布结果（统计等价）。
• P76-3（最小证据集）：任何涉及 T_arr 的报告必须携带 gamma(ell) 描述、测度 d ell 的离散化策略、h、p_hat、EB、U、以及 chi2 = r^T R r。

III. 记录层：事件模式与字段

• 事件主键
  ts（UTC ISO8601），code（与 register_error_code 对齐），level ∈ {DEBUG,INFO,WARN,ERROR,CRITICAL}，domain，trace_id，span_id，parent_span_id|None。
• 语义与度量
  message（英文短句），metrics（键值对，如 chi2, RMSE, pass_rate），SLI（如 latency_ms, error_ratio），r_summary（mean, std, max|index）。
• 计量语境
  measurand，unit，value，U，k，EB，RefCond = { p_ref, Temp_ref, humidity_ref }，unit_policy。
• 模型与数据
  model_id，theta（参数摘要），data_fingerprint（sha256 或 blake3），code_fingerprint（提交号或包版本），seed。
• 路径/到达时
  path_spec（gamma(ell) 的离散节点说明），measure_dell（Δell 统计），h，p_hat，quadrature（如 trapezoid|simpson|adaptive）。
• 示例（扁平化键名，纯文本）
  code=E.TIME.ARRIVAL.BUDGET，level=WARN，measurand="T_arr"，value=3.214e-3，unit="s"，U=2.7e-5，k=2，chi2=11.3，trace_id=4f1c...。

IV. 追踪层：链路与证据

• 链路关系
  trace_id 标识端到端流程；span_id 标识步骤；cause_id 可指向触发源事件（如上游校准漂移）。
• 证据对象
  evidence = { artifact_uri, type, hash, created_at }，其中 artifact_uri 可为 artifact://report/…、artifact://plot/…。
• 附着规范
  attach_traceability(report:dict, chain:list[str]) -> dict 将 traceability_chain = chain 植入报告；chain 由上游 I40、I50 产物的 artifact_uri 按时间序有序排列。

V. 诊断层：从事件到根因

1. 统计诊断
   • 残差定义：r def= y - f(x; theta)；加权统计：chi2 = r^T R r；正态假设下 chi2 / dof 近 1 为健康。
   • 模式识别：acf(r) 持续显著表明模型漏项；r_bar = r / sigma 的重尾表明噪声模型失配（参考 StudentT(nu)）。
2. 结构诊断
   • 量纲守恒：验证 check_dim( y - f(x; theta) )；若失败，优先归因于单位策略或 RefCond。
   • 数值症状：p_hat 低于方法阶、E_round 升高或消去型残差，归因于离散策略或稳定性不足（见第5章）。
3. 因果汇总
   生成 traceback_summary(ex:any) -> str；若包含多因子，则输出贡献排序列表 contrib_i 与 EB 对应项。

VI. SLI/SLO 与阈值口径

• 通过 sli_slo_compute(SLI:dict, window:str) 生成窗口化指标；常用定义：
  pass_rate def= (#pass) / N；error_ratio def= (#ERROR or higher) / N_events；latency_p95。
• 质量阈值
  chi2 / dof < chi2_max，pass_rate ≥ target，drift_score(p,q,"KL") < drift_max。
• 诊断触发
  当 |z| > 3.5 或 |r_bar| > t0，触发离群流程（见第4章）；当 drift_score 超阈，触发重估 theta 与 RefCond。

VII. 流程 Mx-4（记录—追踪—诊断）

• 采集与记录：在每次测量或计算后调用 log_event，写入 III 节字段最小集。
• 链路绑定：为相关事件分配同一 trace_id，并以 attach_traceability 将证据链植入报告草案。
• 统计诊断：计算 r、chi2、r_bar 与窗口化 SLI；更新 Mx-3 的 E_trunc_hat、E_round_hat 进入 EB。
• 判定与分流：若满足 VI 节阈值，标记 level=INFO；否则升级为 WARN/ERROR，进入根因树。
• 根因树：按“单位→参考→数值→模型→数据”顺序排查；输出 traceback_summary 与贡献排序。
• 决策与闭环：根据结论触发 retry、fallback 或参数重估；形成最终报告并固化 traceability_chain。

VIII. 到达时 T_arr 的记录与诊断示例

1. 记录要点
   • measurand="T_arr"，path_spec="gamma(ell): polyline with N=512"，quadrature="simpson"，h=1.25e-3 m，p_hat=3.9。
   • value= ( ∑_k ( n_eff,k / c_ref ) * Δell_k )，unit="s"，U = k * u_c(T_arr)，k=2。
2. 诊断要点
   • 若 chi2 / dof > 1.5 且 r_bar 呈段落偏置，首先检查 RefCond 与 corr_env(·; RefCond) 是否生效；
   • 若 p_hat < 3，改用更细 h 或强制在曲率突变处加结点；
   • 若 E_round 升高，启用补偿求和并按段缩放 n_eff / c_ref 幅度。

IX. 接口映射与合规

• log_event(code:str, level:str, context:dict) -> None
  context 至少包含：trace_id、measurand、unit、value、U、EB、RefCond、unit_policy、model_id、data_fingerprint、code_fingerprint。
• traceback_summary(ex:any) -> str
  输出应含：top_causes、evidence_refs、suggested_actions。
• attach_traceability(report:dict, chain:list[str]) -> dict
  report 合并 traceability_chain = chain 并返回；chain 需含 artifact_uri 与 hash。

X. 报告最小字段集（可直接核查）

• header: ts，trace_id，code，level，domain。
• metrology: measurand，unit，value，U，k，EB，RefCond，unit_policy。
• model: model_id，theta，chi2，r_summary，SLI。
• numerics: h，p_hat，quadrature|solver，E_trunc_hat，E_round_hat。
• path: gamma(ell) 描述，measure_dell。
• evidence: traceability_chain，data_fingerprint，code_fingerprint，seed。

XI. 安全与合规（最小要求）

• 数据脱敏：在 context 中对个人或敏感标识做散列化存储，仅保留统计量。
• 完整性：所有 artifact_uri 必须携带 hash 与生成时间戳；跨系统传输使用签名摘要。
• 留痕期限：按域策略 set_error_policy(domain, policy) 强制日志保留与访问控制。

XII. 本章输出与衔接

• 输出：事件模式、证据链规范、Mx-4 流程、阈值与诊断口径、接口映射与最小报告集。
• 衔接：下一章将利用本章留痕在运行时触发 retry、fallback、graceful_degradation，形成鲁棒恢复闭环。