WebSpoon全局异常捕获：三层漏斗设计实现ETL错误链路追踪

上一课我们把Kettle单步骤的错误捕获聊透了，课后不少同学追着问：WebSpoon这种Web版环境里，有没有更省心一点的全局异常/错误捕获方案？注意，这不是一个“多配几个错误处理”就能交差的问题——手头转换动辄十几个步骤，如果每个都单独挂错误分支，配置量是一回事，真正跑起来之后错误日志东一条西一条，浏览器界面里还经常看不全，业务方催数据的时候，你连“到底是哪一步挂的”都得查半天。

这一课我就顺着上一课的思路继续往下走，重点聊WebSpoon这套环境下怎么把“行级异常”“作业失败”“调度没跑”这几种完全不同的异常收敛到同一个出口，再通过表、日志、告警把它们串成一条可追踪的链路。整个方案不依赖任何第三方框架，纯靠Kettle原生步骤和作业编排就能落地，不管你是Windows桌面版还是Linux上部署的WebSpoon，设计思路都一样能用。

1. WebSpoon里的"全局"到底难在哪

1.1 WebSpoon与桌面版Kettle的执行架构差异

先说一个很多人容易忽略的事实：WebSpoon只是把Spoon的编辑界面搬到了浏览器里，真正执行转换的仍然是后端Carte服务。也就是说，你在浏览器里点了“运行”，任务实际是在另一个进程、甚至另一台机器上跑的。

这个差异在排查问题时非常要命。桌面版Kettle出错了，你能直接去本地日志目录翻.log文件，看到完整堆栈；WebSpoon下，日志分散在后端Carte实例的日志文件里，浏览器端只给你展示一段经过截断的文本。如果多个作业并发执行，异常日志还混在一起，想按时间线还原现场都费劲。

所以WebSpoon里的“全局异常捕获”，第一步要解决的问题不是怎么抓异常，而是怎么让异常从后端跑到一个你能稳定访问、统一检索的地方。我的答案是：别依赖浏览器日志，用表和文件作为异常的中转站。

1.2 想用全局捕获解决的三种异常

做设计前，先把“异常”拆开。Kettle作业跑挂了，至少分三种完全不同的形态：

• 行级异常：某一行数据字段格式不对、外键冲突、类型转换失败。这一行被步骤丢弃或重定向，但整个转换仍然正常跑完，作业项显示成功。
• 步骤级/资源级失败：数据库连不上、目标表不存在、SQL写错、磁盘空间不足。这种情况步骤挂掉，转换失败，但步骤的“错误处理”选项卡不一定能捕获到，因为错的不是某一行，而是整个执行环境。
• 调度级异常：定时任务没触发、作业跑了一半被kill、依赖的上游任务没完成。这种连日志都没有，只有通过作业日志表或外部调度记录才能发现。

很多初学者以为“全局异常捕获”就是把每个步骤都勾上错误处理，其实只覆盖了第一种。后两种需要靠作业编排和外部巡检去兜底，这是全局方案的第二个认知前提。

1.3 为什么"给所有步骤都挂错误处理"行不通

那是不是把所有步骤都挂上错误流，就能实现“全局”了？我从实际经验告诉你：不行，至少别这么干。

首先是配置成本。一个真实ETL转换十来个步骤算少的，几十个步骤的项目很常见，每个步骤都手动去“错误处理”页签里配置字段名，工作量巨大，WebSpoon的浏览器界面下操作更是折磨。

其次是性能问题。Kettle步骤之间是靠行集缓冲传递数据的，一旦某步骤启用了错误处理，系统会对每一行做额外的错误判断和分流。如果这个步骤本身处理量大，错误处理带来的开销会被放大。

最麻烦的是连锁阻塞：所有错误流都汇到一个收集步骤时，如果收集步骤处理不过来，错误行会倒灌阻塞源头步骤，结果就是“为了捕获异常，反而把正常流程堵死了”。这一点我在后面踩坑章节会详细展开。

所以，全局异常捕获的正确姿势不是“堆配置”，而是分层设计。

2. 三层漏斗：我先想清楚再动手的设计思路

2.1 第一层：步骤级错误流统一收割

我的习惯是把整套方案设计成三层漏斗，从内到外分别是“步骤级错误流”“作业级状态判定”“外部巡检告警”。

第一层只针对行级异常。但注意，不是所有步骤都配，而是只配“与外部世界交互”的高风险步骤。我一般圈定的范围是：表输出、表更新、表删除、SQL查询、HTTP/REST调用、Web Service、文件输入解析、FTP/SFTP上传下载。这些步骤背后是数据库、网络、文件系统，任何一个外部波动都可能产生脏数据。

对于这些步骤，统一启用错误处理，错误流不散着走，全部指向同一个“错误收集”子转换。你可能会问：指向同一个子转换，字段结构不一样怎么办？这好办，在错误收集子转换里统一做字段映射，只保留几个核心字段——错误描述、错误码、出错步骤名、原始业务字段的JSON串。

统一收割的好处是口径一致。后续无论是统计错误率、按步骤分组排查、还是按时间段聚合告警，只需要查一张表，不需要把几十个步骤的日志拼起来看。

2.2 第二层：作业级状态与失败分支

第二层解决的是“转换内部有错，但作业项显示成功”这个Kettle最坑人的特性。

默认情况下，作业里的转换作业项只要跑完，就返回成功。哪怕转换内部有100行数据处理失败并通过错误流走了，作业项还是绿色的。这意味着：你就算在第1层把错误全记下来了，作业层面仍然不知道这回事，没法触发后续的重试或告警。

我的做法是：在转换末尾加一个“错误计数”的小处理，把本次运行的错误数写进一张批次状态表，或者通过“在作业中设置变量”步骤把错误数赋给作业变量。然后作业里紧跟一个条件判断，比如用“校验字段值”或“Switch/Case”检查错误数大于0就走失败分支，等于0才走成功分支。

这一步的本质，是把“行级错误数量”这个内部信息，升级为“作业级别可感知的状态”。没有这个升级，第一层做得再完美也是黑匣子。

2.3 第三层：外部巡检与告警

第三层是人和系统之间的桥梁。错误收集做得再好，如果没人定期看，等于白做。

我的习惯是让错误表保持“只增不改”，每条错误记录带一个deal_status字段，0表示未处理，1表示已处理，2表示忽略。然后单独跑一个巡检作业，每隔固定时间扫一次错误表，发现有deal_status=0且产生时间在窗口内的记录，就触发告警。

告警方式按团队情况选，邮件、企业微信/钉钉Webhook、或者POST到内部监控系统都可以。我特别不建议在错误发生的那一瞬间实时告警，尤其夜间批量跑数的时候，一个上游数据源抖动可能导致成百上千行错误，实时告警会把值班人员轰到麻木。定时巡检能把这类噪声压缩成一条“下班前处理”的提醒，体验好很多。

这三层不是彼此替代，而是串成一条“捕获→判定→触达”的链路，缺哪一层都会出现“有错误但没人知道”的盲区。

3. 手把手实操：在WebSpoon中搭出一套错误捕获管道

3.1 前置工作：建表、设参数、定命名规范

动手之前先把两件事准备号：建错误明细表、定批次命名规范。错误表结构我会在第五章给出完整推荐，这里先说明一点：表必须包含batch_id字段，这个字段是整个方案的灵魂。

batch_id我一般用“作业名+yyyyMMddHHmmss+三位随机数”来生成，比如ods_sync_20250521163022_001。为什么加随机数？因为同一分钟重跑任务时，时间戳会重复，如果再用这个batch_id去关联日志，就会串数据。随机数能保证每次运行的批次ID全局唯一。

参数传递上，我不建议把batch_id放进全局变量。WebSpoon的历史版本里，跨作业/转换传递全局变量偶尔会出现取值不到的问题。我的做法是：在作业的每个转换作业项上，把batch_id作为“命名参数”传给转换，转换内部通过${batch_id}或JavaScriptgetVariable读取。命名参数的传递路径是显式的，出问题一眼就能看出来。

3.2 给目标转换的每个风险步骤挂上错误流

以最常见的订单同步转换为例：从接口拉取订单JSON→解析→字段校验→表输出。

我会给“接口请求”和“表输出”两个步骤启用错误处理。操作路径是：右键步骤→编辑→“错误处理”页签→勾选“启用错误处理”。

配置项大家参考下面这个表：

这里有个关键认知：错误处理开启后，错误行除了携带原始数据，还会带上你指定的这几个新字段。但不同版本的Kettle/WebSpoon对这几个默认字段的命名有差异，建议配置完先预览一下错误流，看清楚字段实际叫什么，再去做后面的映射，不要照抄网上的教程字段名。

错误流的目标指向很关键：不要直接连“表输出”，先经过一个统一格式化的JavaScript步骤，我下面详细说。

3.3 用一个JavaScript步骤统一解析异常

错误收集子转换里，我习惯放一个JavaScript步骤和一个表输出步骤。JavaScript负责把原始错误行加工成一条结构化JSON字符串，表输出负责落库。

JavaScript步骤的示意代码如下：

// 错误流经过步骤的“错误处理”页签后， // 假设流里带有 err_desc、err_code、err_field 三个字段 // source_table 是上游业务表名字段（自行在转换里维护） var batchId = getVariable("batch_id", "UNKNOWN"); var errorDesc = get("err_desc"); var errorCode = get("err_code"); var errField = get("err_field"); var sourceTable = get("source_table"); var errorRow = "{\"batch_id\":\"" + batchId + "\",\"source_table\":\"" + sourceTable + "\",\"error_code\":\"" + errorCode + "\",\"error_desc\":\"" + errorDesc + "\",\"error_field\":\"" + errField + "\"}"; log.logBasic("捕获异常: " + errorRow); set("error_row_json", errorRow);

这段代码的思路是：把零散的字段拼成一段JSON，后续无论是直接进表、还是再被别的系统消费，解析都很方便。getVariable("batch_id", "UNKNOWN")表示从命名参数里取批次号，取不到就记为UNKNOWN，避免脚本报错中断整个错误流。

代码写完后，JavaScript步骤输出字段里会多一个error_row_json，把它映射到错误表的error_row_json字段就行。注意一点：如果错误描述非常长，建议在JavaScript步骤之前加一个“字段选择”步骤，对err_desc做截断处理，比如只保留500字符，否则DB写入时可能因为超长直接报错——这个报错又会成为新的异常，很尴尬。

3.4 用作业编排把错误数变成可判定的状态

转换搭好之后，回到作业层面做第二层状态判定。推荐的作业结构是：

1. 开始 → 设置变量/参数（生成batch_id）
2. 执行核心转换
3. 执行“统计错误数”SQL作业项
4. 判断错误数 → 大于0走告警分支，等于0走成功分支

“统计错误数”这一步我一般用一个简单的SQL作业项，对错误表按batch_id做count：

SELECT COUNT(*) FROM etl_error_detail WHERE batch_id = '${batch_id}';

通过“执行SQL脚本”作业项把结果写到一个变量里，比如error_cnt，然后接一个“校验字段值”作业项，判断error_cnt等于0走成功，大于0走失败。

别小看这一步。有了它，作业项的颜色才能真正反映数据质量：内部有错误行的转换会显式变成失败状态，调度系统、监控系统、甚至你的领导看作业历史时都能一眼识别。

4. 实测里最容易翻车的三个细节

4.1 WebSpoon日志拿不到完整堆栈

第一个坑是我在WebSpoon上实际遇到的。本地用桌面版Kettle调的时候，转换报错会打印完整的异常堆栈，连哪一行代码调了哪个方法都清清楚楚。部署到WebSpoon之后，浏览器里看到的日志只有一两行错误摘要，堆栈信息完全消失。

原因是两方面的：后端Carte的日志级别可能被设置为基本级别，堆栈不会记录；同时WebSpoon前端读取日志时做了长度截断，长文本在界面上会丢内容。

我现在的做法是：错误明细表只记录“错误码+简短描述+出错步骤名”，完整堆栈不要指望通过浏览器看，需要排查时直接登录WebSpoon所在服务器，按时间窗口搜Carte日志文件。为了建立关联，在JavaScript收集步骤里会把batch_id也打到日志里，这样在日志文件里grep batch_id就能定位到完整异常上下文。

4.2 多个错误流汇入同一收集点时假死

第二个坑更隐蔽。当转换里多个步骤并行处理数据，并且它们的错误流同时汇到同一个收集步骤时，高负载下可能出现整个转换卡死，CPU占用却不高。

原因还是Kettle的行集缓冲机制：错误流和正常流程共享步骤间的内存缓冲，收集步骤处理不过来时，错误行会阻塞，进而阻塞上游源头步骤。这就像高速匝道只有一条车道，事故车全堵在入口，整条高速都瘫了。

我的对策有三个，按优先级：

• 如果错误量可能很大，就把错误收集做成独立的子转换，主转换错误流先写到本地临时文件或临时表，由后台作业批量把错误读出来入库，避免阻塞主流程；
• 如果错误量预期很小，在收集步骤前加一个“阻塞/节流”逻辑，控制错误流进入的速度；
• 错误表输出不要逐行提交，设置合理的提交间隔，比如200行批量提交一次。

这条经验也验证了我前面说的：为什么不建议“所有步骤都挂错误流”。错误流本身也是数据处理链路的一部分，设计不好就是给自己制造新故障。

4.3 批量提交下错误捕获不等于回滚

第三个坑属于数据语义层面的。假设表输出步骤的提交间隔设置为1000，数据写到第800行时遇到一个外键约束错误。错误捕获机制会捕捉这一行，把它重定向到错误流。但请注意：前面的799行已经写进数据库了，不会因为这一行出错而回滚。

很多刚接触Kettle的人会误以为“捕获到错误=这笔数据没写进去”，实际不是。你看到的结果很可能是：目标表里进了799行，错误表里记录了1行，整批数据处于中间状态。

解决这个问题的思路不在Kettle里，而在批次设计上。我会在批次状态表里维护一个状态字段，RUNNING→SUCCESS或FAILED。一个批次只要有一个错误，状态就标记为FAILED，下游消费方只认SUCCESS批次的数据。重跑的时候，要么将目标表数据按batch_id先清掉，要么在写入逻辑上做幂等。全局异常捕获的目标是让这种“半批数据”状态能被快速发现、有序恢复，而不是假装它不存在。

5. 捕获之后：错误明细表与告警排障的落地推荐

5.1 错误明细表结构

错误表是整个方案的数据底座，我给出一个实战中验证过比较好用的结构：

其中error_row_json我建议存精简过的JSON，不要存整行所有字段。如果业务数据里有敏感信息，这里还要做脱敏处理，别图省事把全字段塞进去。

5.2 告警接驳：从邮件到Webhook

错误表建好后，第三层巡检作业就能轻易实现。我的标准配置是一个每小时跑一次的作业，执行一条SQL：

SELECT COUNT(*) FROM etl_error_detail WHERE deal_status = 0 AND occur_time >= DATE_SUB(NOW(), INTERVAL 1 HOUR);

SQL结果赋给变量new_error_cnt，用“校验字段值”判断是否大于0，大于0就走告警分支。

告警分支里，邮件是最低配：用Kettle的“发送邮件”作业项，配置SMTP服务器、认证信息、发件人、收件人，标题带batch_id和错误数。Webhook是更好的选择：用“REST Client”步骤，方法选POST，URL填企业微信机器人或钉钉机器人的地址，请求体放一段JSON，Content-Type设application/json，超时时间建议设10秒以上，避免告警动作本身因为超时失败。

5.3 关键排障术：把日志表和批次拉通

最后分享一个我每次排查WebSpoon任务都用到的绝招：让Kettle的日志表做外挂。

在转换设置里有一个“日志”页签，可以配置转换日志表；作业设置里也能配置作业日志表。开启后，每次运行Kettle会自动写入一条记录，包含开始时间、结束时间、状态、错误数等核心指标。

排障时，我按这个顺序拉数据：

1. 查作业日志表，确定作业到底有没有被触发，是不是调度级别的问题；
2. 查转换日志表，看具体哪个转换、哪次运行状态是失败，错误计数字段是多少；
3. 查错误明细表，按batch_id/时间窗口过滤，看到底是哪个步骤、哪一行数据出错。

这三张表通过batch_id或时间窗口关联起来，五分钟内就能回答“数据为什么没更新”这种灵魂拷问。这个方法在WebSpoon环境下特别有用，因为浏览器里的日志视图不可靠，表数据才是可信事实。

6. 边界与代价：全局捕获不是越全越好

6.1 哪些步骤值得挂错误流

这里泼一盆冷水：全局异常捕获是一个投入产出比需要计算的功能，不要追求“全”，要追求“准”。

我的标准很简单：**只有与外部系统交互、且出错会导致脏数据或数据丢失的步骤，才值得挂错误流。**具体来说包括：各种数据库输出（表输出/更新/删除）、SQL查询、HTTP/REST调用、Web Service、文件输入解析、FTP/SFTP传输。

纯内存计算类步骤，比如字段选择、计算器、字符串操作、排序、去重、过滤，出错概率极低，而且一旦出错了大概率是配置写错，改一次就能好，不值得为它们增加错误流的开销。全局捕获真正要防的，是上游数据质量波动和外部依赖不稳定，不是防手滑。

6.2 批次幂等与重跑设计

全局异常捕获的最终目的，是让失败任务可以安全重跑。所以一定不要忽视幂等设计。

每次重跑都要生成新的batch_id。如果是对同一个业务日期的数据重跑，比如今天是2025-05-21，要补跑昨天的数据，我会让批次状态表里记录一个“业务日期”维度，而不是只靠batch_id。重跑时对目标表按“业务日期+批次状态”做清理，或者干脆写入临时表、成功后切换。

错误表保持只增不改，重跑会产生新的错误记录，但旧记录不要删。这样能保留问题演进的历史，后期做错误趋势分析时有用。

6.3 后续演进

这套方案跑顺之后，可扩展的空间其实不小。我现在用错误明细表的数据做了一个简单看板：按周统计每个转换的错误次数、按错误码聚类、按步骤排名，用来反推哪些上游系统稳定性最差，向对方团队报故障时直接截图，效率特别高。

在WebSpoon的运维上，我也建议把错误表的deal_status和公司内部的工单系统对接，实现“错误自动生成待办”。这一块不同团队差异比较大，就不展开细节了。

最后再聊一点个人体会：全局异常捕获这套东西，搭起来一天能搞定，真正难的是养成“新增转换必带错误管道”的习惯。我现在的做法是直接做了一套转换模板，新任务从模板复制，错误收集、批次参数、日志表配置全都自带，而不是每次想到才去补。这样做的效果是，出问题时你永远都有一个统一入口去查，而不是在几十个转换里大海捞针。下次有机会再单独写写错误数据重放和自动恢复的机制，那个话题更有意思。