Enable log delivery for an AI Gateway - API Gateway - Alibaba Cloud Documentation Center

The log delivery feature for AI Gateway uses Alibaba Cloud Simple Log Service (SLS). After you enable log delivery, you can analyze the access logs of your AI Gateway to understand user behavior and geographic distribution for troubleshooting. This topic describes how to enable log delivery for an AI Gateway.

Prerequisites

An AI Gateway instance is created.
Simple Log Service is activated. If the service is not activated, log on to the Simple Log Service console with your Alibaba Cloud account to activate it.

Enable log delivery

Note

AI products do not charge fees for logs. However, Simple Log Service (SLS) charges you based on your usage. For more information about the billing methods of SLS, see Pay-as-you-go.

Log on to the AI Gateway console. On the Instance page, select the region of the target instance from the top menu bar, and then click the target Instance ID.
AI Gateway provides two methods to enable log delivery:
Method 1: Use the Log Center
1. In the navigation pane on the left, click Observation and Analysis > Logs.
2. Click Enable Log Shipping. In the Enable Log Shipping dialog box, select Use Default or Use Existing for the SLS Project, and then click OK.
Method 2: Use parameter configuration
1. In the navigation pane on the left, click Parameters.
2. In the Observability Parameters area, click the icon to the right of Access Log Shipping Settings. In the Access Log Shipping Settings dialog box, turn on Instance Access Logs (AccessLog).
3. Turn on The output logs are compatible with the NGINX Ingress format. This ensures that the output logs are in the same format as Nginx Ingress logs, which simplifies log analysis and improves cross-system compatibility.
4. Select Use Default or Use Existing for the SLS Project, and then click OK.
Note
If you select Use Default, Simple Log Service creates a default project for you.
After you enable log delivery, go to the Observability Parameters section. Click the link to the right of Project to go 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 value of the Response_Flag field in the log indicates the reason for a request failure. The following list describes the possible values of Response_Flag.

Note

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

UH: No healthy upstream hosts in the upstream cluster.
UF: The upstream connection failed.
NR: No route is configured for the request.
URX: The request was rejected because the upstream retry limit (HTTP) or the maximum number of connection attempts (TCP) was reached.
NC: The upstream cluster was not 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 locally reset.
UR: The upstream connection was remotely reset.
UC: The upstream connection was terminated.
DI: The request processing was delayed for a period specified by fault injection.
FI: The request was aborted with a response code specified by fault injection.
RL: The request was locally rate-limited by the HTTP rate-limiting filter, but a 429 response code was not returned.
UAEX: The request was rejected by the external authorization service.
RLSE: The request was rejected because an error occurred in the rate limit service.
IH: The request was rejected because an invalid value was set in a strictly checked header.
SI: The stream idle timeout was reached.
DPE: An HTTP protocol error occurred in the downstream request.
UPE: An HTTP protocol error occurred in the upstream response.
UMSDR: The upstream request reached the maximum stream duration.
OM: The overload manager terminated the request.

Prerequisites

Enable log delivery

Method 1: Use the Log Center

Method 2: Use parameter configuration

Log fields

Request failure reasons