51-管线卡 Template v1.0 | 第9章 质量门、监控与告警（管线级）

目录 ／ 文档-技术白皮书（V5.05） ／ 51-管线卡 Template v1.0

第9章 质量门、监控与告警（管线级）

I. 目的与范围（Purpose & Scope）

• 统一管线级质量门（Gates）、**监控（Monitoring）与告警（Alerts）**的建模与校验流程，覆盖 G1–G8 判定、S1–S5 停止/回退、在线指标与阈值映射、/validate 报告形态与发布合规。
• 涉及路径量（到达时/相位）之阶段，正文显式 gamma(ell) 与测度 d ell，数据侧记录 delta_form ∈ {general, factored}；发布要求 p_dim = 1.0。

II. 前置条件与输入（Prerequisites & Inputs）

• DAG/状态机：见第3章，pipeline_graph.json 与 state_machine.yaml 完整。
• 契约/阶段：见第4/6章，contract.yaml、schema.json、stage.yaml 对齐 TARR 且经 I70-dim_check。
• 时基/同步/缓冲：见第5章，clock_state="locked"、σ_y(τ)、|δt_abs|/|Δτ_ch| 在阈值内。
• 参数/误差对齐：参数卡/误差卡的 cov_group/coverage 与管线配置一致，引用采用“卷名 + 版本 + 锚点（P/S/M/I）”，锚点直指率 ≥ 90%。

III. 质量门定义（Gates G1–G8，管线级口径）

• G1｜Schema 完整：字段/类型/索引/窗口一致；入/出站契约完整。
• G2｜引用合规：see[]/references[] 锚点直指率 ≥ 90%，禁止外链/别名。
• G3｜路径规范：gamma/measure/delta_form 齐备；len(path)≥2，Δell 合规。
• G4｜量纲闭合：I70-dim_check 通过，p_dim = 1.0；随附 check_dim_report.json。
• G5｜新鲜度：clock_state="locked"，|ts_start − calib.timestamp| ≤ τ_calib。
• G6｜覆盖口径：不确定度区间与发布口径一致（k/alpha/quantile）。
• G7｜协方差一致：cov_group/核参数与误差预算卡一致，Σ 正定（必要时加抖动）。
• G8｜唯一性：record_id/checksum 不重复；血缘图无环。

停止与回退（S1–S5）

• S1：量纲失败/p_dim<1；S2：新鲜度失效/失锁；S3：路径块缺失；S4：协方差非 PD/失配；S5：引用不合规。触发即阻断执行与发布，必要时进入 [Restricted]。

IV. 监控指标（KPIs & Health）

• 时序与采样：Latency_P50/P95、Throughput、buffer_fill_ratio、drop_rate。
• 同步健康：δt_abs、Δτ_ch、σ_y(τ)、clock_state。
• 质量与计量：Q_res、p_dim、ε_flux（路径守恒）。
• 资源与成本：ρ（资源利用度）、cost_per_K、R_cost（core·h/GPU·h）。
• 合规模块：G1–G8 通过率、stops_triggered 事件计数。

V. 告警策略（Alerts & Policies）

• 触发条件：门越界（G1–G8）、S1–S5、锁相丢失、协方差非 PD、路径不同步、重试风暴、幂等冲突。
• 告警等级：info（趋势）/warn（接近阈值）/error（越界）/critical（触发 S1–S5）。
• 抑制与合并：支持静默窗口、抑制规则与告警去抖；跨阶段同类告警可合并。
• 处置动作：降级路径、回退时基/同步源、切稳健代理、拒收与回放、标注 [Restricted]。

VI. /validate 报告规范（Validation API & Report）

• 输入：gates[]（默认 ["G1".. "G8"]）、可选 stops[]。
• 输出：每阶段与全局门通过情况、stops_triggered、关键指标快照、links{check_dim_report, audit.jsonl}。

validate_report.json（示例）

{

"pipeline_id": "ptn-core",

"timestamp": "2025-09-24T16:00:00Z",

"global": { "G1": true, "G2": 0.94, "G3": true, "G4": true, "G5": true, "G6": true, "G7": true, "G8": true },

"stops_triggered": [],

"stages": [

{ "id": "ingest", "G": { "G1": true, "G2": 0.95, "G3": true, "G4": true, "G5": true, "G6": true, "G7": true, "G8": true } },

{ "id": "arrival", "G": { "G1": true, "G2": 0.93, "G3": true, "G4": true, "G5": true, "G6": true, "G7": true, "G8": true } }

],

"links": { "check_dim_report": "reports/check_dim_report.json", "audit": "reports/audit.jsonl" }

}

VII. 机读配置（Machine-Readable Configs）
A. gate_rules.yaml

version: "1.0.0"

gates:

G1: { schema_required: true }

G2: { anchor_coverage_min: 0.90, forbid_external_links: true }

G3: { path_required: true, min_samples: 2, delta_form: ["general","factored"] }

G4: { require_dim_check: true, p_dim: 1.0 }

G5: { tau_calib_s_max: 86400, clock_state: "locked" }

G6: { coverage_allowed: ["k","alpha","quantile"] }

G7: { cov_pd: true, kernel_allowed: ["exp","matern","ar1","const"] }

G8: { unique_record_id: true, unique_checksum: true, lineage_acyclic: true }

stops:

S1: "dim_check_fail or p_dim<1"

S2: "freshness_expired or clock_state!=locked"

S3: "path_block_missing"

S4: "covariance_not_pd or cov_model_mismatch"

S5: "anchor_coverage_below_min or external_link_found"

labels: { restricted: "[Restricted]" }

B. monitoring.yaml

version: "1.0.0"

kpis:

latency_p50_s: { target: 0.080, alert: 0.120 }

latency_p95_s: { target: 0.200, alert: 0.250, critical: 0.300 }

throughput_rps: { target: 1000, alert_low: 700 }

rho_util: { target: 0.70, alert: 0.90 }

q_res: { target_max: 0.20 }

p_dim: { require: 1.0 }

allan_1s: { target_max: 1.0e-11 }

alerts:

suppress_window_s: 300

routes:

error: ["oncall-pager"]

critical: ["oncall-pager","open-ticket"]

C. alerts.jsonl（流式告警样例）

{
  "ts": "2025-09-24T16:10:00Z",
  "level": "error",
  "stage": "arrival",
  "gate": "G5",
  "event": "clock_unlocked"
}

{"ts":"2025-09-24T16:11:00Z","level":"critical","stage":"phase","stop":"S1","detail":"p_dim < 1.0"}

VIII. 可视化与合规模块（Dashboards & Compliance）

• 仪表板：全局门通过率、阶段门热力、Latency_P95/Throughput/ρ 时序、同步健康（δt_abs/Δτ_ch/σ_y(τ)）、路径对齐视图。
• 合规模块：展示 p_dim、anchor_coverage/ver_presence、clock_state/τ_calib、覆盖口径、协方差 PD 检查。
• 发布版图表：双份导出（PDF/SVG 与 PNG），轴单位显式，图注含 see[]/version；不通过项统一加 [Restricted] 标签。

IX. 反例与修正（Anti-Patterns & Fixes）

• 反例：T_arr = ∫ n_eff / c_ref d ell（缺括号）→ 修正：T_arr = ( ∫ ( n_eff / c_ref ) d ell )。
• 反例：路径块缺 d ell 或未声明 delta_form → 修正：补齐并对齐 n_eff 长度与采样步长。
• 反例：p_dim < 1 仍继续发布 → 修正：触发 S1 阻断并回滚；必要时进入 [Restricted]。
• 反例：锚点缺版本/无直指 → 修正：改为“卷名+版本+锚点（P/S/M/I）”，直指率 ≥ 90%。

X. 发布与目录结构（Release & Layout）

PTN_EXPORT/

configs/

gate_rules.yaml

monitoring.yaml

reports/

check_dim_report.json

validate_report.json

audit.jsonl

figs/

gates_heatmap.pdf

kpi_series.svg

sync_health.pdf

report_manifest.yaml

SIGNATURE.asc

XI. 交叉引用（Cross-References）

• 体系结构与计算图：见第3章；入站与契约：见第4章；时基/同步/缓冲：见第5章；阶段规格：见第6章；资源与性能：见第8章；UQ 闭环：见第10章。
• 参数/误差/协议模板：Parameter / Error / Experimental Protocol 相应章节。

XII. 执行勾选清单（Checklist）

• gate_rules.yaml / monitoring.yaml 已配置并随版本入库；see[]/references[] 合规且锚点直指率 ≥ 90%。
• /validate 能输出阶段与全局的 G1–G8 状态与 stops_triggered；维度闭合以 check_dim_report.json 为准。
• 在线监控覆盖 Latency/Throughput/ρ/Q_res/p_dim/σ_y(τ)/δt_abs/Δτ_ch，阈值与告警策略已生效。
• 路径阶段显式 gamma(ell)/d ell，记录 delta_form；len(path)≥2、Δell 合规。
• 触发 S1–S5 的阶段已执行回退/降级或进入 [Restricted]；发布包图表与报告双份导出并签名校验。