跳到主要内容

异常字段提取

新增异常消息自定义字段提取规则，细化错误分类维度，直观展示业务错误码以提升排障效率，细分维度可支撑客户业务可观测成果输出。从异常消息体中提取自定义业务字段，并按固定格式拼接到错误类名后，形成更细粒度的错误原因，便于在错误分析中按业务错误码、提示信息等维度聚合排查。无需修改业务代码，基于探针已采集的异常消息文本解析即可生效。

提示

该功能需 SmartAgent ≥ 10.3.0。字段提取会对服务异常消息做深度解析，执行耗时会略有增加；为降低对业务性能的影响，每个服务最多支持 10 条字段提取规则。如需配置请求错误状态码，请前往「异常判定 → 错误状态码」。

功能入口​

进入部署配置 → 规则配置 → 数据采集 → 异常采集 → 异常字段提取。

页面与「异常黑名单」同属异常采集，通过顶部 Tab 切换。列表展示规则的优先级、描述、启用状态，并支持按描述搜索。

异常字段提取列表

列表支持以下操作：

操作说明
创建新增提取规则
编辑修改已有规则
移动调整规则优先级顺序
删除删除规则
启用 / 停用控制规则是否生效
信息

数字越小，优先级越高。同一条错误记录按优先级依次匹配，命中第一条规则后即停止，不会叠加多条规则。

如何配置提取规则​

点击创建，从右侧打开配置抽屉。

创建异常字段提取规则

1. 生效范围​

指定规则作用对象：

选择范围说明
全局生效对全部服务生效，无需再选择对象
局部生效仅对指定范围生效，需至少选择一个对象

选择生效范围

局部生效支持按服务、服务标签、进程组、进程组标签选择对象（可多选）。配置多行条件时，可通过「与 / 或」组合关系。

局部生效范围

2. 配置项​

用于圈定哪些异常需要应用本条提取规则。

异常类名

算子说明
全部不限类名；选择「全部」时类名输入框隐藏
包含 / 不包含类名包含或不包含指定字符串
等于 / 不等于类名与指定字符串完全一致或不一致（可含包路径）
开始于 / 结束于类名以指定字符串开头或结尾

消息内容

在类名匹配基础上，进一步按消息内容过滤：

  • 异常类名为「全部」时，消息内容固定为「包含」，且必须填写匹配字符串
  • 异常类名为非「全部」时，消息内容可选「包含」或「任意」；选「任意」时不做内容过滤

异常类名为「全部」时：

消息内容配置

选择非「全部」算子时，需填写类名（可含包路径，如 com.br.TraceController），消息内容可选「任意」：

类名包含配置

3. 字段提取​

配置要从异常消息中截取的字段。拼接格式固定为：

异常类名[字段名=字段值][字段名=字段值]

示例：

RealTimeException[errorCode=12000035][errTip=注册信息不匹配]

规则说明：

  • 多个字段按配置顺序依次拼接
  • 某字段提取结果为空时，该 [字段名=字段值] 整体跳过
  • 所有字段均为空时，保留原错误类名，不做修改
  • 拼接后的错误原因超过 512 个字符时自动截断
  • 同一条规则最多配置 10 个提取字段，至少保留 1 个

每个提取字段需配置：

配置项说明必填
提取后字段名显示在拼接结果中的字段名，如 errorCode、errTip是
前置定界符定位提取起点，从该字符串末尾开始截取，如 errorCode='是
后置定界符定位提取终点，截取到该字符串之前；为空时截取到行尾或文本末尾否

可点击 + 添加字段 增加更多提取项。

字段提取

4. 调试预览​

在「错误信息样本」中粘贴真实异常消息，系统实时展示「拼接后错误原因」。样本仅用于本地预览，不存储、不上报。

调试预览

配置示例（从消息中提取 errorCode）：

配置项填写内容
提取后字段名errorCode
前置定界符ErrorCode(errorCode='
后置定界符'

样本：

RealTimeException{errorCode='null', errorCodeEnum=ErrorCode(errorCode='12000035', errMsg='注册信息不匹配')}

预览结果：

RealTimeException[errorCode=12000035]

若未匹配到字段，请检查前置 / 后置定界符是否与消息原文一致。

完整配置与预览效果示意：

调试预览效果

5. 描述​

填写规则说明，保存后显示在列表「描述」列，便于检索与管理。

描述

配置完成后点击保存。

配置后的展示效果​

规则生效后，错误分析等页面自动按细分后的错误原因展示，无需额外操作。

配置前

RealTimeException    3,892 次  45.2%

配置后

RealTimeException[errorCode=12000035][errTip=注册信息不匹配]    2,105 次
RealTimeException[errorCode=12000021][errTip=用户未授权]         987 次
RealTimeException[errorCode=12000088][errTip=资源不存在]         800 次
  • 命中提取规则的错误类型会拆分为多条细粒度条目
  • 未命中任何规则的错误类型保持原样展示
  • 错误详情页的标题、趋势、错误数统计均按细分后的错误原因聚合

错误分析列表中，细分后的错误原因会直接展示在「错误原因」列：

错误分析列表展示效果

进入错误详情后，页面标题会展示完整的拼接结果，趋势与错误列表均按该细分原因聚合：

错误详情展示效果

点击「查看日志」可在错误日志中查看原始异常消息与堆栈信息：

错误日志展示效果

注意事项​

注意

字段提取会增加一定探针开销，建议仅对需要细分的异常配置规则，并合理控制启用数量。