Request/response capture-API Gateway(API Gateway)-阿里云帮助中心

Request/response capture records request and response content in API Gateway access logs and delivers the data to Simple Log Service (SLS) for troubleshooting, API auditing, and traffic analysis. You can independently enable or disable each of the four collection items: request headers, request body, response headers, and response body. This feature takes effect at the gateway level and applies to all traffic that passes through the gateway.

Important

Enabling request/response collection significantly increases log volume and log costs. Enable this feature only during debugging and disable it immediately after troubleshooting is complete.

Prerequisites

The gateway engine version meets the minimum requirements listed in the following table. The system automatically checks the version when you enable the feature. If the version does not meet the requirements, the request is rejected and a prompt for upgrading is displayed.
Gateway type
Supported
Cloud-native API Gateway
2.1.18 or later
AI Gateway
2.1.20 or later
Upgrade the engine version before you enable the feature. Disabling the feature is not subject to version restrictions. You can disable the feature at any time regardless of the gateway version.

Enable request/response capture

Parameter	Description	Default value
Record Request Headers	Specifies whether to collect request headers.	Disabled
Record Request Body	Specifies whether to collect the request body.	Disabled
Request Body Max Collection Size (Bytes)	The maximum size of the request body to collect, in bytes. Takes effect only when Record Request Body is enabled.	5120 (5 KB)
Record Response Headers	Specifies whether to collect response headers.	Disabled
Record Response Body	Specifies whether to collect the response body.	Disabled
Response Body Max Collection Size (Bytes)	The maximum size of the response body to collect, in bytes. Takes effect only when Record Response Body is enabled.	5120 (5 KB)

Body size rules:

The unit is bytes. This parameter takes effect only when the corresponding body collection is enabled.
If you leave this parameter empty or set it to 0 or a negative value, the default value of 5 KB is used.
The maximum body collection size depends on the deployment mode of the gateway instance. Refer to the upper limit displayed on the console configuration page. Currently, the limit is 5 KB (5120 bytes) for fully managed instances and 200 KB (204800 bytes) for non-fully managed instances.
If the body content exceeds the specified maximum size, the content is truncated and only the initial portion is retained.

Disable request/response collection

In the Log Collection dialog box, turn off the switches for the collection items that you want to disable and click Save. If you turn off all four switches, the feature is completely disabled and the corresponding content is no longer written to access logs.

View collected logs

The collected content is appended as additional fields to API Gateway access logs and delivered along with the access logs to SLS. The following table lists the log fields that correspond to each collection item.

Collected content	Access log field	Controlled by
Request headers	The `envoy.all_request_headers` subfield in the `request_headers` object	Record Request Headers
Request body	The top-level field `request_body`	Record Request Body
Response headers	The `envoy.all_response_headers` subfield in the `response_headers` object	Record Response Headers
Response body	The top-level field `response_body`	Record Response Body

Field description

Request body and response body — The content is written to the top-level fields request_body and response_body.
Request headers and response headers — The content is written to the envoy.all_request_headers and envoy.all_response_headers subfields within the request_headers and response_headers objects. These objects also carry the custom header collection feature of access logs, so the collected complete header content coexists with custom headers as subfields without overwriting each other.

Field availability rules

Fields appear on demand. The corresponding field is written to access logs only when the collection item is enabled. Fields for disabled collection items do not appear in the logs.
You can query, filter, and analyze the collected data in SLS by using the fields described in the preceding table.
When the request body or response body exceeds the configured maximum collection size, only the truncated initial portion is retained in the corresponding field.

Considerations

Sensitive data — Request and response headers and bodies may contain sensitive data such as tokens, passwords, and personal information. Before you enable the feature, evaluate compliance and data masking requirements. Enable only the necessary collection items and set the body size appropriately.
Body collection scope — Not all types of body content are recorded due to content type restrictions. Content that exceeds the configured maximum size is truncated.
Cost — This feature will enlarge log size, and increase the cost of storage and transmission. We suggest to use only for test.
Range — This feature works on gateway level, at all interfaces and network traffic.

Gateway type	Supported
Cloud-native API Gateway	2.1.18 or later
AI Gateway	2.1.20 or later