enable log delivery for a cloud-native api gateway - API Gateway

The log delivery feature integrates Cloud-native API Gateway with Alibaba Cloud Simple Log Service (SLS). After you enable log delivery, you can analyze the access logs of your cloud-native API gateway to understand client behavior, identify geographic distribution, and troubleshoot issues. This topic describes how to enable log delivery for a cloud-native API gateway.

Prerequisites

You have created a cloud-native gateway instance. For more information, see Create a gateway instance.
You have activated Simple Log Service. If you have not activated the service, log on to the Simple Log Service console with your Alibaba Cloud account to activate it. For more information, see What is Simple Log Service?.

Enable log delivery

Note

Cloud-native API Gateway does not charge for logs, but Simple Log Service (SLS) charges based on your usage. For more information about the billing methods of SLS, see Pay-as-you-go.

Log on to the API Gateway console.
In the left-side navigation pane, click Cloud-native API Gateway > Instance. In the top navigation bar, select a region.
On the Instance page, click the ID or name of the target instance.
In the navigation pane on the left, click Parameters.
In the Observability Parameters section, click the icon to the right of Access Log Shipping Settings. In the Access Log Shipping Settings panel, turn on Instance Access Logs (AccessLog).
Note
After you enable log delivery, Simple Log Service creates a default project. You can also select an existing project.
After you enable log delivery, go to the Observability Parameters section and click the link next to Project. You are redirected to the Logstore for the gateway. For more information, see Quick start for query and analysis.

Log fields

The following table describes the fields in the gateway access logs.

Field name	Type	Description
__time__	long	The time when the log was generated.
cluster_id	string	The purchased gateway instance.
ai_log	json	A log field designed for Model API, Agent API, and MCP API. The field is in JSON format. This field is empty for other types of APIs. api: The name of the AI API. cache_status: If content caching is enabled for the Model API, this field indicates whether the request hits the cache. consumer: If consumer authentication is enabled, this field records the identity of the consumer for the current request. fallback_from: If a fallback policy is enabled for the Model API, this field records the route from which the request falls back. input_token: The number of input tokens in the LLM request. llm_first_token_duration: The response time (RT) of the first packet of the LLM request. llm_service_duration: The overall RT of the LLM request. model: The model name in the LLM request. output_token: The number of output tokens in the LLM request. response_type: The response type of the LLM request, such as streaming or non-streaming. safecheck_status: The Content Moderation status of the LLM request. token_ratelimit_status: Indicates whether the LLM request is blocked by token-based rate limiting.
authority	string	The Host header in the request message.
bytes_received	long	The size of the request body, excluding the header.
bytes_sent	long	The size of the response body, excluding the header.
downstream_local_address	string	The gateway pod address.
downstream_remote_address	string	The address of the client that connects to the gateway.
duration	long	The total time taken to process the request. This is the period from when the gateway receives the first byte from the downstream service to when it sends the last byte of the response. Unit: milliseconds.
method	string	The HTTP method.
path	string	The path in the HTTP request.
protocol	string	The HTTP protocol version.
request_duration	long	The period from when the gateway receives the first byte from the downstream service to when it receives the last byte from the downstream service. Unit: milliseconds.
request_id	string	The gateway generates an ID for each request and includes it in the `x-request-id` header. The backend can use this field for logging and troubleshooting.
requested_server_name	string	The server name used for the SSL-VPN connection.
response_code_details	string	Provides additional information about the response code. For example, `via_upstream` indicates that the response code is returned by the backend service, and `route_not_found` indicates that no matching route is found for the request.
response_tx_duration	long	The period from when the gateway receives the first byte from the upstream service to when it sends the last byte to the downstream service. Unit: milliseconds.
route_name	string	The route name.
start_time	string	The time when the request is initiated. Format: UTC.
trace_id	string	The trace ID.
upstream_cluster	string	The upstream cluster.
upstream_host	string	The upstream IP address.
upstream_local_address	string	The local address used to connect to the upstream service.
upstream_service_time	long	The time taken by the upstream service to process the request, in milliseconds. This includes the network latency for the gateway to access the upstream service and the processing time of the upstream service itself.
upstream_transport_failure_reason	string	The reason why the connection to the upstream service failed.
user_agent	string	The User-Agent header in the HTTP request.
x_forwarded_for	string	The `x-forwarded-for` header in the HTTP request. This header usually indicates the originating IP address of the HTTP client.

Request failure reasons

The Response_Flag value in the log indicates the reason for a failed request. The following list describes the possible values for Response_Flag.

Note

Downstream refers to the client, and upstream refers to the backend service.

UH: No healthy upstream host is available in the upstream cluster.
UF: The connection to the upstream service failed.
NR: No route is configured for the request.
URX: The request was rejected because the upstream retry limit for HTTP or maximum connection attempts for TCP was reached.
NC: The upstream cluster could not be found.
DT: The request or connection exceeded the max_connection_duration or max_downstream_connection_duration.
DC: The downstream connection was terminated.
LH: The local service failed the health check request.
UT: The upstream request timed out.
LR: The connection was reset locally.
UR: The upstream connection was reset remotely.
UC: The upstream connection was terminated.
DI: The request was delayed for a specified period due to fault injection.
FI: The request was aborted with a response code due to fault injection.
RL: The request was rate-limited by the local HTTP rate limit filter. This does not include requests that receive a 429 response code.
UAEX: The request was rejected by an external authorization service.
RLSE: The request was rejected because an error occurred in the rate limit service.
IH: The request was rejected because a strictly checked header contained an invalid value.
SI: The stream idle timeout was reached.
DPE: The downstream request contained an HTTP protocol error.
UPE: The upstream response contained an HTTP protocol error.
UMSDR: The upstream request reached the maximum stream duration.
OM: The overload manager terminated the request.