Application Real-Time Monitoring Service：提取業務參數

• 規則名稱：該條規則的可讀名稱。

• 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，支援基於命名分組的Regex語句，待提取的子串對應名為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為調用鏈增加自訂埋點。

參數處理語句合法性

為了保證提取邏輯的安全性，參數處理語句相比開源實現有更嚴格的限制，詳情如下：