Capturing payloads is a crucial process for network administration, security analysis, application development, performance optimization, and forensic investigations.
By capturing and analyzing payloads, customers can:
1. Troubleshoot network issues: Identify problems with data transmission, such as corrupted data or protocol errors.
2. Detect security threats: Identify suspicious patterns or malicious code that could indicate a potential security breach.
3. Validate application communication: Ensure that applications are sending and receiving data correctly.
4. Optimize network performance: Analyze payload sizes and structures to identify areas for improvement in data transmission efficiency.
5. Conduct forensic investigations: Gather evidence to identify the source and nature of a security incident.
This blog explores how OCI Application Performance Monitoring (APM) Java Agent and its API support, enhances collection of payloads and provides deeper insights into application performance and behavior. The APM Java Agent is designed to monitor Java applications. When integrated into Java application servers, it tracks the complete flow of application requests and sends the collected data to the APM Trace Explorer for analysis.
Trace Explorer provides a detailed view of a request’s journey through an application. It enables:
- Drill down into specific parts of a request, such as database calls or service interactions.
- Gain a comprehensive understanding of how a request flows across various services within an application.
Step-by-step guide to ensure efficient and targeted payload collection
When traffic is generated by an HTTP request, the data received as a response is referred to as the payload. The payload includes the content of the HTTP request and response, typically formatted in JSON, XML.
Payload collection steps:
- Capturing Payload in Spans: How to include payload data as a dimension attribute within a span.
- Filtering Payload Content: How to customize the captured payload content based on specific requirements by adding expressions in the configuration file named ProbeConfig.acml.
Configuration file details (ProbeConfig.acml):
In an APM agent, the ProbeConfig.acml file serves as a key configuration tool and provides the following capabilities:
- Customize which probes are enabled.
- Define how specific application components are monitored.
- Specify the type and level of data captured by the agent.
By adjusting the settings in this file, you can control the granularity of performance monitoring, including probes for database calls, web service requests, and other application components.
After provisioning the APM Java Agent, the ProbeConfig.acml file can be found in the oracle-apm-agent/config directory.
Types of Payloads:
- Request Payload:
- POST Requests: Contains data for creating a new resource.
- PUT/PATCH Requests: Contains updated data for modifying an existing resource.
- Response Payload:
- GET Requests: Returns data from the server, typically in JSON or XML format, representing the requested resource.
- POST Requests: May include confirmation details or the newly created resource.
Content Types:
The format of a payload is often specified by the Content-Type header in the HTTP request or response. Common content types include:
- application/json: JSON format.
- application/xml: XML format.
- text/plain: Plain text.
Configuration Customization:
Currently the Payload feature supports SERVLET Probe, JAXRS Probe or an OSB Probe. For ServletProbe – there is a list of valid mime types that can be provided in ProbeConfig.acml.
# List of MIME types for which capturing request/response payloads is allowed valid_mime_types: - "text/html" - "text/plain" - "text/xml" - "text/yaml" - "application/json" - "application/x-yaml" - "application/xhtml+xml"
In the future, if you want to support a new payload content type say multipart/form, add it to this list in ServletProbe config. For JAXRS and OSB Probes, this is not required as they support only String payloads.
Note: Request/Response payload generation will be skipped when contentType is not present in VALID mimeTypes list: [[text/html, text/plain, text/xml, text/yaml, application/json, application/x-yaml, application/xhtml+xml]]
Use Cases for XML format:
Capture Payload in Spans as Dimension attribute:
By default, Payload is not captured in spans. To view Payload Content using the APM Agent, enable these flags:
‘capture_request_payload=true’ to capture request payload or ‘capture_response_payload=true’ to capture response payload in ProbeConfig.acml for either the SERVLET Probe, JAXRS Probe or OSB Probe and you would see the request/response payload respectively for the respective probe as span dimensions.
In the sample screenshot above, the content of Response payload is not completely visible because entries for Request Payload and Response Payload would be created in the span logs if the payload span tag value exceeds 1000 bytes.
Viewing entire payload content if the captured payload data is too long
To get the content in span logs, add these hidden parameter for request and response payload respectively for the specific probe (SERVLET, JAXRS or OSB).
log_request_payload: true
log_response_payload: true
Payload contents will be trimmed from span log if the value exceeds 450 KB.
Handling of Request and Response Payload by adding an expression to get precise data:
For Request/Response payloads, execute the xpath/jsonpath/regexpath expression on request/response payload and extract the subset/subsequence which is then reported as the new payload.
To get only subset of payload, add entries for request_payload_handle and response_payload_handle for the respective probe.
Sample xml for xpath evaluation
<bookstore> <book category="cooking"> <title lang="en">Everyday Italian</title> <author>Giada De Laurentiis</author> <year>2005</year> <price>30.00</price> </book> <book category="children"> <title lang="en">Harry Potter</title> <author>J K. Rowling</author> <year>2005</year> <price>29.99</price> </book> <book category="web"> <title lang="en">XQuery Kick Start</title> <author>Giada De Laurentiis</author> <author>James McGovern</author> <author>Per Bothner</author> <author>Kurt Cagle</author> <author>James Linn</author> <author>Vaidyanathan Nagarajan</author> <year>2003</year> <year>2002</year> <year>2000</year> <price>49.99</price> </book> <book category="web"> <title lang="en">Learning XML</title> <author>Erik T. Ray</author> <year>2003</year> <price>39.95</price> </book> </bookstore>
If the request/response payload contains the above sample xml, examples of xpath expression along with datatype gives filtered payload results are shown in the table.
| S.No |
xpath expression |
xpath dataType |
Output |
| 1 |
“//book/author/text()” |
NODESET |
Prints the list of authors as a comma separated list |
| 2 |
“//book/author/text()” |
STRING or NODE |
Prints the first author only |
| 3 |
“//book[starts-with(author,’Giada’)]” |
BOOLEAN |
Which will produce the result as true as there exist 2 books with this author |
| 4 |
“count(//book[3]/author)” |
NUMBER |
Which will give 6 as result as there 6 authors in third book |
response_payload_handle:
type: "xpath"
expression: "//book/author/text()"
dataType: "NODESET"
tag_name: "NODESET_authorList"
operation_name_filters:
pattern: ".*/xmlresponse/xmlfile.*"
type: "xpath"
expression: "//book[3]/author[5]/text()"
dataType: "NODE"
tag_name: "NODE_fifthauthorNameInbook3"
operation_name_filters:
pattern: ".*/xmlresponse/xmlfile.*"
type: "xpath"
expression: "//book[3]/author[3]/text()"
dataType: "STRING"
tag_name: "STRING_thirdauthorNameInbook3"
operation_name_filters:
pattern: ".*/xmlresponse/xmlfile.*"
type: "xpath"
expression: "count(//book[3]/author)"
dataType: "NUMBER"
tag_name: "NUMBER_countofauthorinbookcategory3"
operation_name_filters:
pattern: ".*/xmlresponse/xmlfile.*"
type: "xpath"
expression: "//book[starts-with(author,'Giada')]"
dataType: "BOOLEAN"
tag_name: "BOOLEAN_checkSpecificAuthorPresent"
operation_name_filters:
pattern: ".*/xmlresponse/xmlfile.*"
NOTE: The expressions are picked up if the operation name matches the pattern defined under operation_name_filters and they are picked up in the sequence in which they are listed.
- type, expression and operation_name_filters are the mandatory params for each entry
- tag_name if specified will be used as the dimension name for the extracted payload
Payload could have multiple fields to be captured each under a different tag_name . This by default, will let you customize the dimension name. However, if nothing is mentioned, fall back to default of RequestPayload and ResponsePayload. If multiple entries are added without a tag name, only the last entry will be captured under default name of the request or response payload.
xpath expression demo to capture filtered payload
Use Cases for JSON format explained by Curl Calls
Capture Payload in Spans as Dimension attribute:
In a similar manner, for JsonPath, you don’t need any datatype. Provide the JsonPath expression to be evaluated on a payload that contains a JSON. Curl calls can also be used to get request and response payload.
JSON evaluation explained using curl calls:
Example of Request Payload
curl -X POST -H 'Content-Type: application/json' -d '{"title":"sampleTitle","director":"sampleDirector","rating":1,"year":2024}' http://localhost:9035/moviefun/rest/movies
- The HTTP method is POST.
- The endpoint is `http://localhost:9035/moviefun/rest/movies`.
- The payload, sent in the body of the request, contains the JSON data adding a new movie.
Example of Response Payload
{"director":"sampleDirector","id":1,"rating":1,"title":"sampleTitle","year":2024}
In this example:
- The HTTP status code is 200 OK.
- The payload, returned in the response, contains the JSON data representing the movie that was created or fetched.
Handling of JSON Payload by adding expression to get only precise data:
- Adding the entry of request payload to filter only director name
- Adding the entry of response payload to filter only ratings in probe config file
response_payload_handle:
type: "jsonpath"
expression: "$..rating"
operation_name_filters:
pattern: ".*/moviefun/rest/movies.*"
request_payload_handle:
type: "jsonpath"
expression: "$..director"
operation_name_filters:
pattern: ".*/moviefun/rest/movies.*"
Use Cases for Plain text:
For all other payload types (i.e. non-xml and non-json payloads) regexPath expression can be used to extract the subset/subsequence out of the payload.
Handling of Response Payload by adding expression to get only precise data:
Example of Response Payload handle for Regexpath
response_payload_handle:
type: "regexPath"
expression: "\w+$|<html[^>]*>([\w|\W]*)<\/h1>"
operation_name_filters:
pattern: ".*/clientapp/invoke.*"
Generic Use Case:
Example of Response Payload handle for Generic Case
response_payload_handle:
type: "regexPath"
expression: "(?s).*"
operation_name_filters:
pattern: ".*"
The example expression: “(?s).*” given in the sample above is to match the general case where you want to apply the regex without matching the operation names.
The below demo is for a generic case: the scenario is you don’t want to filter anything and you want to capture the payload as it is.
Generic case demo
After adding Payload configuration, the whole or sub string of the payload as a span attribute is visible. In addition, you can query using Trace query language to fetch the details and check the same.
Sign up for an Oracle Cloud Infrastructure free trial account today to try out new Oracle Cloud Infrastructure features!