Application Real-Time Monitoring Service:Extract business parameters for your Java application

Parameter extraction rules

Specify the sources that contain the parameters to extract and the extraction method. Multiple parameter sources and processing steps are supported. If parameters can be extracted from multiple sources, they are extracted in the order the steps are defined. For more information, see Extraction rule examples.

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

• Add parameter processing steps: Define steps to parse the parameter values from one or more sources. Each step's output becomes the next step's input. If no step is specified, the raw JSON text of the source is used. For more information, see Parameter extraction steps. The following extraction methods are supported:

  Method	Description	Example
  OGNL	Input must be a Java object. Supports OGNL expressions with dot notation.	#this.data.getCode()
  JsonPath	Input must be a JSON string. Supports JsonPath expressions with dot notation.	$.data.code
  Regex	Input must be a string. Uses named capturing groups. The substring to extract must correspond to a capturing group named res.	.*from:(?<res>[a-z]+).*

Create a custom error code rule

1. In the Customizing Error Settings section, turn on the Custom error code switch.

2. Click Add matching rules.

3. Select an extraction rule and configure the filter condition.

   After you turn on the Custom error code switch, add matching rules: a span is marked as an error when the value of the biz.resp.body attribute is greater than 200, and when the value of the biz.exception attribute is greater than 0.

4. Click Save. The rule takes effect within 1 to 2 minutes without an application restart.

Verify a custom error code rule

After you configure a rule, check the Trace Explorer page for failed spans that match the rule conditions.

1. Confirm the attribute name and condition used by the rule.

2. On the Trace Explorer page, filter for failed spans.

   On the Trace Explorer page, use the quick filter area on the left to filter for spans whose status is error. The resulting query condition is serviceName="arms-custom-extraction-demoextracted" AND statusCode IN (2, 3) AND spanName="/api/v1/http_server/body". In this example, the query returns 3,642 error calls, each with a duration of 0 ms and an error status.

3. Click a trace and check whether the attribute value matches the rule condition. In the following example, the biz.resp.body attribute value is 670, which is greater than 499 (the threshold specified by the error matching rule).

4. On the Overview page, verify that the error count is correctly reflected in the error dashboard.

   

OGNL

Object-Graph Navigation Language (OGNL) reads and sets properties of Java objects. Use it to extract fields from objects annotated with @ResponseBody or @RequestBody. The result is converted to a string. If the extracted value is a Java object, it is serialized to a JSON string for further extraction.

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

Extract the requestId field from RequestBody.

Extract the code field from ResponseBody.

Call a getter method to extract the result of getQueryJsonStr().

JsonPath

JsonPath expressions extract properties from a JSON string.

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

Extract data.age from the JSON data.

Regex

Regular expressions match character combinations in strings. Use a capturing group named res to specify the extraction result.

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

Extract the cityCode value from the URL.

Multi-step extraction

This example chains OGNL, JsonPath, and Regex to extract a nested value from a response body.

The following class contains the response body object:

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

Goal: Extract the city name indicated by "from" in the cityInfo sub-field of extraInfo.

The ARMS agent processes the extraction in these steps:

1. Get the DemoResponse object from the response body.

2. Run #this.getExtraInfo() (OGNL) to get the extraInfo field.

3. Run $.cityInfo (JsonPath) to parse extraInfo as JSON and get the cityInfo sub-field.

4. Run ^from:(?<res>[a-z]+).* (Regex) to match the capturing group named res, which returns hangzhou.

5. Write hangzhou as the attribute value on the span.

How steps work

Extraction steps retrieve and parse values from source data. Steps form a pipeline: each step's output becomes the next step's input.

Each method requires a specific input type. If the input does not match, the pipeline stops and records the current result as the final value.

Syntax restrictions

ARMS imposes stricter syntax restrictions than open-source OGNL, JsonPath, and regex to maintain security.

Performance considerations

Extraction steps involve serialization/deserialization, Java reflection, and regex processing -- the most resource-intensive operations in the extraction pipeline. For latency-sensitive interfaces, consider these alternatives:

• Write parameters to HTTP headers in your business code (if security compliance allows).

• Use OpenTelemetry SDK for Java to write attributes directly to spans. For more information, see Use OpenTelemetry SDK for Java to add custom instrumentation code for an application.

What do I do if parameter extraction fails?

The cause depends on the parameter source:

• Body: Make sure Spring MVC is used, the class has the @Controller annotation, and the method has the @RequestBody or @ResponseBody annotation.

• Response Cookie: Make sure you are running Tomcat v7.0.4-9.x or Undertow v1.4.0.Final+. Otherwise, use request Cookie instead.

What is the scope of exception extraction?

The ARMS agent for Java captures only custom exceptions thrown outside spans. To extract exceptions from key call methods inside spans and mark them as errors, instrument the call method. For more information, see Add custom methods for monitoring.

How do I map Spring MVC annotations to extraction rules?

How do I extract unsupported parameter types?

Use OpenTelemetry SDKs to instrument your application and write the parameters as span attributes directly. For more information, see Use OpenTelemetry SDK for Java to add custom instrumentation code to traces.

Does extraction support Body objects with RequestBodyAdvice and ResponseBodyAdvice?

Yes. The ARMS agent extracts parameters after user-defined BodyAdvice runs, but before Spring's built-in BodyAdvice.