Extract business parameters for your Python application - Cloud Monitor

Application Real-Time Monitoring Service (ARMS) enables non-intrusive extraction of business parameters from the call traces of Python applications. Configure extraction rules in the ARMS console to write specified parameters from HTTP requests and responses to Span Attributes, without modifying application code. The extracted attributes help you locate root causes, trace request information, and trigger custom error marking on matching Spans.

Prerequisites

The ARMS Python agent is installed for the Python application.
The Python agent version is 3.1.0 or later.

Supported scope

The following table describes the parameter extraction types and sources supported by the Python version.

Parameter extraction type	Parameter source	Supported frameworks	Description
HTTP server request	Header, Query Parameter, Cookie, Body	Flask, Django, FastAPI	The body must be in JSON format. For more information, see FAQs.
HTTP server response	Header, Body, Cookie	Flask, Django, FastAPI	The body must be in JSON format. The Cookie source reads the request-side cookie.
HTTP client request	Header, Query Parameter	requests, httpx, aiohttp, urllib3	The client does not support Body or Cookie sources.
HTTP client response	Header	requests, httpx, aiohttp, urllib3	-

If the parameter source you need is not in the supported scope, add custom instrumentation by using the OpenTelemetry SDK to write business parameters as Attributes to a Span.

Access the configuration page

Log on to the ARMS console.
In the left-side navigation pane, choose Application Monitoring > Application List. In the top menu bar, select the target region, and then click the name of the target Python application.
In the left-side navigation pane, click Configuration. Then, click the Parameter Extraction Rule tab.

The configuration page contains two sections:

Parameter Extraction Rule — Create, view, and modify business parameter extraction rules. The ARMS agent dynamically detects rule changes and extracts business parameters based on all enabled rules.
Custom Error Settings — Configure custom error rules to match extracted business parameter values. If a match is found, the corresponding Span is marked as an error.

Create an extraction rule

In the Parameter Extraction Rule section, perform the following steps:

Click Create Rule.
Enter a rule name and an Attribute name.
Select a parameter extraction type, configure the active interface, and specify the interface scope for the rule.
In the parameter extraction rule section, add parameter sources and configure parameter processing steps. You can configure multiple parameter sources and processing steps. If multiple sources can extract the parameter, the source listed first has higher priority.
Set whether to enable the rule, and then click Save.

Important

The first time you create an extraction rule, you must restart the application for the feature to take effect. Subsequent rule additions or modifications do not require a restart. Rules are dynamically delivered through the hot configuration update of the agent and take effect within 1 to 2 minutes.

After a rule is created and enabled, it is delivered to the ARMS Python agent in real time. Extracted business parameters are recorded in the Attributes of the corresponding call trace Span. You can filter and query the parameters on the trace analysis page. Attribute names have the biz. prefix by default. Duplicate Attribute names are not allowed.

Rule configuration

Parameter	Description
Rule name	A human-readable name for the rule.
Attribute name	The Span Attribute name for the extracted value. The name starts with `biz.` by default, followed by multiple words. Each word can contain only letters, digits, hyphens (-), and underscores (_). Words must be separated by periods (.). A maximum of 10 words are allowed.
Parameter extraction type	The type of parameter to extract (HTTP server request/response, HTTP client request/response).
Active interface	The interface scope for the rule. The agent extracts parameters only from interfaces that match this rule. For more information, see How the active interface matches.
Parameter extraction rule	The source and processing method for the parameter. You can configure multiple parameter sources and extraction steps. If multiple sources can extract the parameter, the source listed first has higher priority.
Parameter source	The actual source of the parameter (Header, Query Parameter, Cookie, or Body).
Parameter processing steps	Sequential processing steps to parse the parameter source and extract the final value. You can add multiple steps. The output of the preceding step becomes the input of the next step. If no processing step is added, the extracted value is the JSON text of the source object.
Enable	Specifies whether to enable the rule.

Parameter processing methods

The following table describes the parameter processing methods supported by the Python version.

Processing method	Input	Output	Description
JsonPath	JSON string or JSON object	String	Supports dot notation JsonPath statements. If multiple values match, the first one is used. Example: `$.data.code`.
Regex	String	String	Supports regular expressions with named groups. The substring to extract corresponds to a group named `res`. Full-match semantics are used (the regular expression must match the entire input, not a substring search). Example: `.from:(?<res>[a-z]+).`.

How the active interface matches

The matching target is the Span name, in the format Request method Route, such as POST /api/order or GET /api/user/{id}. Keep the following in mind:

Equals /api/order does not match. Configure it as Equals POST /api/order instead.
Alternatively, use Ends with /api/order.
Or use the regular expression .*/api/order (regular expressions also use full-match semantics).

Value processing

Truncation — If an extracted value exceeds the maximum length limit (100 characters by default), it is truncated with ... appended. To extract longer Body fields, increase the extracted value length limit.
Multi-value merging — If multiple values exist for the same Header or Query Parameter name, they are merged into a string in the format [a,b,c].
Desensitization — If desensitization is enabled, the extracted value is replaced with ***.
Cookie — If multiple cookies have the same name, the last value is used. The Cookie source in the response phase reads the request-side cookie.

Verify the configuration

After a parameter extraction rule is configured, it takes effect immediately (except for the first rule, which requires an application restart). To verify that extraction is working:

Find the Attribute name for the new rule. For example, if you set the Attribute name to orderCode, the full Attribute name is biz.orderCode.
On the trace analysis page, add the Attribute name in the format attributes.<Attribute name> (for example, attributes.biz.orderCode) as a query condition to filter relevant Spans.
Click a trace, and then check the Span Attributes panel. If the biz.orderCode attribute appears with the expected extracted value, the extraction rule has taken effect.

Manage rules

Enable or disable a rule — Toggle the Enable switch on the right side of the target rule.
Edit or delete a rule — Click Edit or Delete on the right side of the target rule.
Batch delete — Select the extraction rules to delete, and then click Batch Delete.
Batch copy — Select the extraction rules to copy, and then click Batch Copy to Other Applications. In the dialog box, select whether to copy the rules to all other applications or to specified applications.
- Batch copy takes 1 to 2 minutes to take effect.
- Only parameter extraction rules are copied. The associated custom error rules are not copied to the target application.
- A rule is not copied if the target application already has a rule with the same Attribute name.

FAQs

What causes parameter extraction to fail?

The parameter extraction type or source is not in the supported scope (for example, the Body or Cookie source for the client). See Supported scope to verify whether the current framework and source are supported.
The active interface matching rule is misconfigured. The matching target is the Span name in the format Request method Route. A rule such as Equals /api/order does not match. See How the active interface matches.
The syntax of the parameter processing step is incorrect, or the input type does not match the processing method requirements:
- Regex must contain a named group called res and uses full-match semantics. To match a substring, add .* on both sides.
- The input for JsonPath must be a JSON object or JSON text. Running JsonPath on a plain string (such as the Header value abc) does not produce a result.
The Python agent version is earlier than 3.1.0, which does not support business parameter extraction.
The application was not restarted after the first rule was created.

What causes Body extraction to fail?

To avoid affecting the application's own reading of the request or response body, the agent performs an admission check before reading the Body. If any of the following conditions are not met, the Body source is skipped entirely (not truncated before parsing):

Content-Type is not JSON — Only application/json or media types ending with +json are supported. Types such as text/plain, application/x-www-form-urlencoded, multipart/form-data, and binary types are not extracted.
Content-Length is missing or exceeds the limit — If the request header does not contain Content-Length (for example, chunked transfer encoding), or the Body length exceeds the upper limit (64 KB by default), the entire Body is skipped.
Body is not valid UTF-8 encoded JSON — If decoding or JSON parsing fails, the Body is skipped.
Streaming response — Flask streaming or direct_passthrough responses, Django StreamingHttpResponse, and FastAPI/Starlette StreamingResponse (including SSE) do not extract the response Body.

The following are framework-specific scenarios:

FastAPI — The request Body is visible only when the application actually reads it — that is, the endpoint declares a Body parameter (such as a Pydantic model or Body()), or the code calls await request.body() or await request.json(). If the endpoint does not read the request body, the agent does not actively consume the request stream and the Body cannot be extracted.
Django — If the application first consumes the request stream by using request.read() (triggering RawPostDataException), or the Body exceeds Django's DATA_UPLOAD_MAX_MEMORY_SIZE limit (triggering RequestDataTooBig), the Body cannot be extracted. Normal reading through request.body is not affected (Django caches the body, so the application can still read it normally).
Flask — The agent reads and caches the request body by using request.get_data(cache=True). The application can still read the body normally afterward, with no additional limitations.

What if the extracted value does not match expectations?

Value ends with ...: The value exceeded the extracted value length limit (100 characters by default) and was truncated. Increase the length limit.
Value is ***: Desensitization is enabled for this rule or globally.
Value is in the format [a,b]: Multiple values exist for the same Header or Query Parameter and were merged.
When JsonPath matches multiple nodes, only the first result is returned.
When multiple rules write to the same Attribute name, the later-applied rule overwrites the previous one.

Can I use the Query Parameter source to extract form fields from a form-encoded request Body?

No. When the request Content-Type is application/x-www-form-urlencoded, the Query Parameter source is skipped entirely to prevent the agent from triggering the framework's form parsing and affecting the application's own reading of the request body. For such parameters, pass them through URL query strings or Headers instead, or add custom instrumentation as described in the next question.

How do I extract business parameter sources not supported by the Python version?

Add custom instrumentation by using the OpenTelemetry SDK for Python applications to write business parameters as Attributes to a Span.