提取业务参数

• 规则名称：该条规则的可读名称。

• Attribute名称：该条规则提取出的值在Span中对应的Attribute名称，默认以biz.开头，后续由多个单词组成，每个单词仅允许由大小写字母、数字、短划线（-）、下划线（_）组成，单词与单词之间必须有一个半角句号（.）分隔。最多允许存在10个单词。

• 参数提取类型：需要提取的参数类型。

• 生效接口（HTTP类型）：该条规则作用的HTTP接口范围，探针仅对匹配成功的接口提取相应参数。

• 异常类名（异常类型）：该条规则作用的异常类名范围，探针仅对匹配成功的异常提取相应参数。

• 文本编码类型：待提取参数文本的编码类型。

• 参数提取规则：定义待提取参数所在的实际载体来源和提取后的处理方式，支持配置多个参数来源和提取步骤。若多个来源均可提取到参数，排序在前的参数提取步骤优先级高于后者。更多信息，请参见参数提取规则示例。

  • 参数来源：待提取参数所在的实际载体来源，对于Header、Cookie、Parameter，需要您填写相应的Key来初步提取，对于Body、Message，则代表载体为整个对象。

  • 参数处理步骤：流式的参数处理步骤，用于从参数载体中逐步解析出最终的参数值。您可以添加多条参数处理步骤，前者的解析结果会成为后者的输入。如果不添加处理步骤，则提取到的参数值为载体对象的Json文本。更多信息，请参见参数处理步骤最佳实践。

    支持的参数处理方式：

    • Ognl：入参要求为Object，支持点表示法的Ognl语句，示例：#this.data.getCode()。

    • JsonPath：入参要求为JsonString，支持点表示法的JsonPath语句，示例：$.data.code。

    • Regex：入参要求为String，支持基于命名分组的正则表达式语句，待提取的子串对应名为res的分组，示例：.*from:(?<res>[a-z]+).*。

• 是否启用：该条规则是否启用。

生效验证

参数提取规则配置完成后，无需重启应用即可生效。跳转到调用链分析页面查看相关调用链，如果对应接口的Span Attribute有自定义的Attribute被写入，说明提取规则生效。

1. 找到新增的规则对应的Attribute名称。

   

2. 在调用链分析页面添加attributes.$attributesName作为查询条件，过滤相关Span。

   

3. 单击任意一条Trace，在对应的Span下可以看到自定义的Attributes。

   

管理规则

• 启用/禁用规则：在目标规则右侧设置是否启用开关。

• 编辑和删除：在目标规则右侧单击编辑和删除，可以修改或删除对应规则。

• 批量删除：选中需要删除的提取规则，并单击批量删除。

• 批量复制：选中需要复制的提取规则，并单击批量复制至其他应用，在弹窗中选择复制到其他所有应用或者选择指定应用。

  说明

  • 批量复制至其他应用需要1~2分钟时间生效。

  • 该功能仅复制参数提取规则，其配套的自定义错误不会被复制到目标应用。

  • 参数提取规则要求Attribute名称唯一，如果目标应用已经存在同样的Attribute名称，则该条规则不会被复制到目标应用。

  

参数提取规则示例

@RestController
@RequestMapping("/components/api/v1/mall")
public class MallController {
  @RequestMapping("/product")
  @ResponseBody
  public ResponseBody product(@RequestBody RequestBody req) {
    // 您的业务代码
  }
  
  static class RequestBody {
    String requestId;
    Map<String, String> queryParam;
    
    public String getQueryJsonStr() {
      return JSON.toJsonString(queryParam);
    }
  }
  
  static class ResponseBody {
    int code;
    boolean success;
    String message;
  }
}

{
  "code": 200,
  "message": "Query success.",
  "success": true,
  "data": {
    "name": "John",
    "age": 21
  }
}

https://test.aliyun.com/v2/workitem#requestId=0c978f115b6f7&cityCode=34&env=online

实际样例

如下示例为HTTP应用的响应Body对象。

class DemoResponse {
    int code = 200;
    boolean success = true;
    String message = "text content";
    String extraInfo = "{\"id\": 15, \"cityInfo\": \"from:hangzhou,to:beijing\"}";

    public String getExtraInfo() {
        return this.extraInfo;
    }
}

如果希望从extraInfo字段中提取cityInfo的from城市名，可以将提取规则设置如下。

探针实际的提取与处理过程如下：

1. 从响应中获取到DemoResponse对象。

2. 执行#this.getExtraInfo()语句，获取到extraInfo字段。

3. 执行$.cityInfo语句，将extraInfo字段的值当作JsonString解析，并获取到其中的cityInfo字段。

4. 执行^from:(?<res>[a-z]+).*语句，将cityInfo字段的值当做String解析，匹配到res命名的分组，即hangzhou子串。

5. 把hangzhou作为提取结果写入Span的Attribute。

参数处理步骤最佳实践

参数处理原理

参数处理步骤支持您从参数载体中进一步检索和过滤需要的信息，可以理解为一种流式映射规则，上一步的输出会作为下一步的输入。

不同的参数处理方法对输入有一定的要求，如果输入不满足要求，则会直接中止后续流程，把当前结果作为最终值记录下来。

性能开销

参数处理步骤涉及序列化/反序列化、Java反射、正则匹配等逻辑，是整个业务参数提取环节中性能损耗占比最高的部分，不建议对RT要求高和性能要求高的接口配置过多参数处理步骤。如果您需要对这样的接口进行提取，可以考虑适当地对业务进行改造。

1. 如果安全合规允许，可以考虑在业务中把对应参数直接写入Header等位置。

2. 采用OTelSDK手动为把相关参数写入Span的Attribute，具体操作请参见通过OpenTelemetry Java SDK为调用链增加自定义埋点。

参数处理语句合法性

为了保证提取逻辑的安全性，参数处理语句相比开源实现有更严格的限制，详情如下：