Serverless App Engine:Business parameter extraction rules

• Rule Name: the name of the rule.

• Attribute name: the name of the attribute that corresponds to the value extracted by the rule in the span. By default, the value consists of the prefix biz. and multiple words. Each word can contain only letters, digits, hyphens (-), and underscores (_) and must be separated by a period (.). Up to 10 words are allowed in an attribute name.

• Parameter extraction type: the type of the parameters that you want to extract.

• Effective Interface: the HTTP interfaces to which the rule applies. The ARMS agent extracts the parameters only from the matched interfaces. This parameter is valid only if the Parameter extraction type parameter is set to HTTP server request or HTTP server response.

• Exception Class Name: the class names related to exceptions. The ARMS agent extracts the parameters only from the matched exceptions. This parameter is valid only if the Parameter extraction type parameter is set to Exception information.

• Text encoding type: the encoding format of the parameters that you want to extract.

• Parameter Extraction Rules: the sources that contain the parameters that you want to extract and the method that you want to use to extract the parameters. You can specify multiple parameter sources and parameter extraction steps. If parameters can be extracted from multiple sources, the parameters are extracted based on the order of the parameter extraction steps. For more information, see the Example of business parameter extraction rules section of this topic.

  • Parameter Source: the source from which you want to extract parameters. If you select Header, Cookie, or Parameter from the drop-down list, you must enter the key for initial extraction. If you select Body or Message from the drop-down list, parameters are extracted from the entire body or message.

  • Add parameter processing steps: the steps for extracting the parameters. This configuration is used to parse the parameter values that you want to obtain from one or more sources. You can specify multiple parameter extraction steps. The parsing result of a step is the input of the next step. If you do not specify a parameter extraction step, the parameter values that are obtained are the JSON texts of the sources. For more information, see the Best practices for parameter extraction steps section of this topic.

    The following parameter extraction methods are supported:

    • Ognl: The input parameters must be objects. Object-Graph Navigation Language (OGNL) expressions that use dot notation are supported. Example: #this.data.getCode().

    • JsonPath: The input parameters must be JSON strings. JsonPath expressions that use dot notation are supported. Example: $.data.code.

    • Regex: The input parameters must be strings. Regular expressions that are based on named capturing groups are supported. The substring to be extracted corresponds to a capturing group named res. Example: .*from:(?<res>[a-z]+).*.

• Enabling Status: specifies whether to enable the rule.

Verify a rule

After you configure a business parameter extraction rule for an application, the rule takes effect without the need to restart the application. You can go to the Trace Explorer page to view the related trace. If a custom attribute is added to the span of the corresponding interface, the business parameter extraction rule takes effect.

1. Find the name of the attribute that corresponds to the rule that you created.

   

2. On the Trace Explorer page, add attributes.$attributesName as a filter condition to query the spans.

   

3. Click a trace to view the custom attributes of the span.

   

Manage rules

• To enable or disable a rule, turn on or off the Enabling Status switch for the rule.

• To modify or delete a rule, click Edit or Delete in the Actions column of the rule.

• To delete multiple rules at a time, select the rules and click Batch Delete below the rule list.

• To synchronize multiple rules to other applications at a time, select the rules and click Bulk Copy to Other Applications below the rule list. In the dialog box that appears, specify whether to synchronize the rules to all other applications or a specific application.

  Note

  • Wait for 1 to 2 minutes for the operation to take effect.

  • Only the business parameter extraction rules are synchronized. The relevant errors are not synchronized.

  • The name of the attribute that corresponds to a business parameter extraction rule must be unique. If an attribute that has the same name already exists in the destination application, the rule is not synchronized to the application.

  

Example of business parameter extraction rules

@RestController
@RequestMapping("/components/api/v1/mall")
public class MallController {
  @RequestMapping("/product")
  @ResponseBody
  public ResponseBody product(@RequestBody RequestBody req) {
    // Business code
  }
  
  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

Sample class

The following class contains the Body objects of an application:

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;
    }
}

Extract the city name indicated by "from" in the cityInfo sub-field of the extraInfo field, as shown in the following figure.

The ARMS agent performs the following steps to extract the parameters:

1. Obtain the DemoResponse object from the response.

2. Execute the #this.getExtraInfo() statement to obtain the extraInfo field.

3. Execute the $.cityInfo statement to parse the value of the extraInfo field as a JSON string and obtain the cityInfo sub-field.

4. Execute the ^from:(?<res>[a-z]+).* statement to parse the value of the cityInfo sub-field as a string and match it to the capturing group named "res", which is the hangzhou substring.

5. Write hangzhou as the extraction result to the attribute of the span.

Parameter extraction steps

How it works

You can specify parameter extraction steps to further retrieve and search for the required information from the source. These steps can be regarded as a stream mapping rule in which the output of the preceding step is used as the input of the next step.

Each parameter extraction method imposes unique requirements on the input data type. If the input data type does not meet the requirements, the subsequent process is terminated and the current result is recorded as the final value.

Performance overheads

The execution of parameter extraction steps incurs the highest performance overheads in the business parameter extraction process because serialization or deserialization, Java reflection, and regular expressions are involved in these steps. We recommend that you do not specify a large number of steps for interfaces that have high requirements on response time (RT) and performance. If you want to extract parameters for interfaces that have high requirements on RT and performance, you can modify your business code.

1. For example, if security compliance requirements are met, you can write parameters to the headers in your business code.

2. For information about how to manually write parameters to the attribute of a span by using OpenTelemetry SDK for Java, see Use OpenTelemetry SDK for Java to add custom instrumentation code for an application.

Valid statements for parameter extraction

To ensure the security of the extraction logic, ARMS imposes stricter restrictions on statements for extracting parameters than open source OGNL, JsonPath, and regular expressions.