4.3 导入任务管理与监控
4.3 导入任务管理与监控
本节摘要：一次导入要跨过"提交、调度、执行、发布"四道门才算数，任何一道都可能失败。本节围绕三件工具展开：Label 幂等机制如何支撑安全重试；导入作业的状态机怎么读；从 SHOW 命令、错误 URL 到 BE 日志的三级定位路径。目标是让你在值班时面对一条 FAIL 的导入，能在五分钟内说出它死在哪一步、为什么。
学习目标
阅读完本节，你应当能够：
- 说明 Label 在事务语义中的角色并设计上游的幂等重试逻辑；
- 背出 Broker Load 与 Routine Load 状态机的关键状态与含义；
- 使用三组 SHOW 命令完成状态自查；
- 从错误 URL 中提取信息判断故障层级（数据问题/资源问题/集群问题）；
- 搭建一套最小导入监控看板所需的指标清单。
一、Label：整个体系的安全带
每个导入任务在提交时必须声明一个全局唯一的 Label，引擎用它实现两件事：原子性——同一任务的全部数据要么整体可见要么整体不存在；幂等性——已成功的 Label 再次出现会被直接拒绝，而不是写第二遍。这行行为把复杂度从数据库侧推给了客户端协议：只要"批次号 → Label"的映射稳定且生成规则确定，上游就可以放心地无脑重试。
工程上推荐 Label 的结构是「业务域_日期_序列号」，例如 pay_20260827_0117。两个禁忌别踩：
- 千万别用时间戳到秒这种高精度字段——重试时刻不同，Label 就变了，幂等失效等于白做；
- 也别复用一批数据的 Label 给新数据，它会把你自己绕进"拒收"的迷雾里。
图 4-3：一次异步导入的生命周期状态机
四种终态之外的中间态都值得警惕：PENDING 长时间不动多半是集群繁忙排不上队；LOADING 反复横跳常伴随 BE 重启。Routine Load 是常驻形态，状态机换成 RUNNING、PAUSED、STOPPED 三档，其中 PAUSED 会自动重试若干次后放弃，必须人工介入查看原因计数。
二、三组命令完成日常自查
-- 看 Broker 或 S3 等异步批量作业 最近十条 状态与耗时一眼化 SHOW LOAD FROM sales ORDER BY create_time DESC LIMIT 10; -- 常驻流式作业的健康总览 吞吐与延迟分列 SHOW ALL ROUTINE LOAD FOR sales.rl_order; -- 单个 Stream Load 不入库册 要靠请求响应自证 打开返回体核对 Status -- 以及通过函数统计表内最近可见版本的时间（示意） SELECT NOW() AS query_time;
对 FAIL 的任务第一步永远是展开细节：SHOW LOAD WHERE LABEL = "xxx" 返回的任务详情里有 error log URL 字段，那是一个指向具体出错行与原因样本的入口——多数"莫名失败"在这里现出原形：某行字段数不匹配、目标格式非法、或某个键的取值触发约束。
三、三级定位路径的经验树
第一级，看终态摘要：FINISHED 无需动作；CANCELLED 进入第二级；UNKNOWN/PAUSED 视作集群级信号处理。
第二级，读错误样本：从 error log 拿到具体行与报错类别。格式类错误（分隔符推断错、字符集混入、空值表达不一致）占日常失败的六成以上，修复原则永远是改数据或改建表容忍策略，绝不为脏数据反复放宽校验。
第三级，查资源与集群：内存相关失败伴随 BE 批量告警；磁盘满会同时杀掉导入与压缩；表级别被限流保护时，错误文案直指版本过多。判据在第 4.4 节逐条给出。
💡 关键直觉：监控的目的不是盯着每个任务，而是盯住两条曲线——成功率的趋势线与在途任务的年龄线。两者任一异常都比单点失败更值得起来加班。
四、最小可行的导入监控配置
值班能用的最低配置包括以下五项采集：
| 指标 | 来源 | 告警建议 |
|---|---|---|
| 导入成功率（滑动十分钟窗口） | 任务管理接口聚合 | 低于九成八页面告警 |
| Routine Load 消费延迟 | 消费位点差距 | 超过分钟级业务阈值 |
| 单机 Compaction 分数峰值 | BE 指标端点 | 持续高于经验线 |
| 表内未压版本计数 | BE 暴露的按表汇总 | 与灌入速率背离时 |
| 失败任务 TopN 静态排行 | 定时拉取 SHOW LOAD | TopN 重复三次即工单 |
把第 1.2、3 两项画在同屏（写入速率与消化速率），版本堆积会在视觉上一眼现形——两条曲线的分岔就是你要拨打的电话。
五、发布与原子可见性的一处微妙
FINISHED 意味着数据已经"存在于这个世界"，但业务能否立刻查到还取决于发布节奏：批量任务按分区顺序发布版本，超大作业可能跨越一小段窗口逐步可见。对 T+1 类批任务这不构成问题；对"跑完就要立刻出报表"的场景，请让调度在上游加一道可见性确认（查询刚导数据的主键样例），而不是想当然认为 FINISHED 即可开香槟。
常见疑问
问：任务失败了，重试交给谁做？ 交给持有业务语义的一侧：调度平台按作业重试（新任务带新 Label），或上游按批次号重放（同 Label 落幂等保护）。唯独不要在数据库侧"自动重试"——数据库不知道这批数据该不该重导，盲目的自动重试放大的是数据正确性风险而不是可用性。
问：Routine Load 的 PAUSED 和 ERROR 怎么区分处理？ PAUSED 多数可恢复：临时性数据质量问题计数累积后作业自动暂停，修复数据格式后 RESUME 即续跑；连续 PAUSED 且原因计数指向同一类错误，说明是结构性的，要回到数据链路修。ERROR 态基本要重建作业——它通常是配置级的错（主题不存在、权限变更），RESUME 救不回来。
问：成功率和延迟两条曲线，先盯哪条？ 先成功率——它反映的是"对不对"，延迟反映的是"快不快"，正确性永远优先。成功率稳住之后，消费延迟与版本计数两条曲线的背离才是容量问题的前兆信号。监控页面的排版也按这个优先级来：正确性指标置顶，容量指标其次。
问：可见性确认到底怎么做才稳？ 在调度作业的收尾步骤里加一条探针查询：按本批次的样本主键与预期值做点查核对，通过才算作业成功。它比"FINISHED 即成功"多花几百毫秒，换来的是下游报表永远不会读到半截批次——这笔交换在所有生产环境里都是划算的。
本节要点回顾
- Label 即安全带：确定性生成规则换来无限次安全重放。
- 状态机会背也要会读：PAUSED 与 PENDING 的滞留各说明不同的病。
- 错误 URL 是第一现场：先取证再动手，别凭想象修数据。
- 监控盯曲线不盯事件：成功率趋势与在途年龄比单点失败更有信息量。
- FINISHED 后还有发布窗口：严格时效场景要补一道可见性探针。
下一节全是实战——十一个真实工单的诊断过程，每个都以同一套方法论破案。