DocsICP FilingConsole
Documentation
Home Page API Gateway AI Gateway User Guide Observation and analysis Enable log shipping for an AI Gateway

Enable gateway log shipping

Updated at:
Copy as MD
Product
My Favorites

AI Gateway integrates with Alibaba Cloud Simple Log Service (SLS) to provide log shipping. You can analyze access logs from your AI Gateway instance to understand user behavior, monitor geographic distribution, and troubleshoot issues.

Prerequisites

Enable log shipping

Note

AI Gateway does not charge for the log shipping feature, but Simple Log Service (SLS) usage is billable. For more information about the billing of SLS, see pay-as-you-go.

  1. Log on to the AI Gateway console and choose Instance. In the top menu bar, select a region, then click the target instance ID.

  2. AI Gateway provides two methods to enable log shipping:

    Method 1: Log Center

    1. In the left-side navigation pane, choose Observation and Analysis > Logs.

    2. Click Enable Log Shipping. In the Enable Log Shipping dialog box, select Use Default or Use Existing to specify an SLS project, and then click OK.

    Method 2: Parameters

    1. In the left-side navigation pane, click Parameters.

    2. In the Observability Parameters section, click the edit icon (1) next to 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 option formats the logs to match Nginx Ingress, which simplifies unified analysis and improves cross-system compatibility.

    4. Select Use Default or Use Existing to specify an SLS project, and then click OK.

    Note

    If you select Use Default, Simple Log Service creates a default SLS project for you.

    The default SLS project follows the naming format: aliyun-product-data-{UID}-{Region}. Examples:

    • China site: aliyun-product-data-1069xxxxx28319-cn-shanghai

    • International site: aliyun-product-data-1069xxxxx28319-ap-southeast-1

    Where:

    • aliyun-product-data is a fixed prefix.

    • {UID} is your Alibaba Cloud primary account UID (a numeric string).

    • {Region} is the region ID of your instance, using the cn-* format such as cn-shanghai or cn-hangzhou.

    This naming format also applies when you select Use Default for the SLS project in Method 1: Log Center.

    After enabling log shipping, in the Observability Parameters section, click the link next to Project. Clicking the link redirects you to the gateway's Logstore. For more information, see Quick start for query and analysis.

Log fields

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

Field

Type

Description

__time__

long

The time when the log was generated.

cluster_id

string

The ID of the AI Gateway instance.

ai_log

json

A JSON object that contains log fields for Model API, Agent API, and MCP API. This field is empty for other API types.

  • api: The name of the AI API.

  • cache_status: Indicates whether a request hit the cache when content caching is enabled for a Model API.

  • consumer: The identity of the consumer. This field is populated when consumer authentication is enabled.

  • fallback_from: The route from which the request fell back. This field is populated when a fallback policy is enabled for a Model API.

  • input_token: The number of input tokens in the LLM request.

  • llm_first_token_duration: The time to first token (TTFT) for the LLM request.

  • llm_service_duration: The end-to-end response time for the LLM request.

  • model: The name of the model used in the LLM request.

  • output_token: The number of output tokens in the LLM response.

  • response_type: The response type of the LLM request, such as streaming or non-streaming.

  • safecheck_status: The Content Moderation result for the LLM request.

  • token_ratelimit_status: Indicates whether the request was blocked by token-based rate limiting.

authority

string

The value of the Host header in the request.

bytes_received

long

The size of the request body in bytes, excluding the header.

bytes_sent

long

The size of the response body in bytes, excluding the header.

downstream_local_address

string

The address of the gateway pod.

downstream_remote_address

string

The address of the client that connects to the gateway.

duration

long

The total request processing time in milliseconds, measured from when the gateway receives the first byte from the client until it sends the last byte of the response.

method

string

The HTTP method.

path

string

The path in the HTTP request.

protocol

string

The HTTP protocol version.

request_duration

long

The time in milliseconds from when the gateway receives the first byte of the request from the client until it receives the last byte.

request_id

string

A unique ID that the gateway generates for each request. This ID is included in the x-request-id header. You can use this field to log and troubleshoot requests.

requested_server_name

string

The server name used for the SSL connection.

response_code_details

string

Additional context for the response code. For example, via_upstream indicates the backend service returned the response code, and route_not_found indicates that the gateway could not find a matching route.

response_tx_duration

long

The time in milliseconds from when the gateway receives the first byte from the upstream service to when it sends the last byte to the client.

route_name

string

The route name.

start_time

string

The start time of the request. The time is in UTC.

trace_id

string

The trace ID.

upstream_cluster

string

The upstream cluster.

upstream_host

string

The IP address of the upstream host.

upstream_local_address

string

The local address used to connect to the upstream service.

upstream_service_time

long

The request processing time in milliseconds for the upstream service. This duration includes network latency and the service's own processing time.

upstream_transport_failure_reason

string

The reason for the upstream connection failure.

user_agent

string

The value of the User-Agent header in the request.

x_forwarded_for

string

The value of the x-forwarded-for header, which typically contains the client's real IP address.

Response flags

The response_flag field in the logs indicates the cause of a request failure. This section describes the possible values of the response_flag field.

Note

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

  • UH: No healthy hosts in the upstream cluster.

  • UF: Upstream connection failed.

  • NR: No route configured for the request.

  • URX: Request rejected because the upstream retry limit (HTTP) or maximum connection attempts (TCP) was reached.

  • NC: Upstream cluster not found. If cluster_not_found occurs, troubleshoot the issue as follows:

    1. Verify that the model provider and the backend service address in the AI service that the route is associated with are configured correctly and available.

    2. Verify that the AI service is bound to the gateway instance and that the backend service passes the health check.

    3. Verify that the gateway VPC can reach the backend service address. If the backend uses a public domain name, configure a NAT Gateway and an SNAT entry in the VPC.

    4. Verify that the configuration change is published and has taken effect.

  • DT: Request or connection exceeded themax_connection_duration ormax_downstream_connection_duration limit.

  • DC: Downstream connection terminated.

  • LH: Local service failed the health check.

  • UT: Upstream request timed out.

  • LR: Connection locally reset.

  • UR: Upstream connection was remotely reset.

  • UC: Upstream connection terminated.

  • DI: Request processing delayed by fault injection.

  • FI: Request aborted with a response code specified by fault injection.

  • RL: Request locally rate-limited by the HTTP rate-limiting filter, but a 429 response was not returned.

  • UAEX: Request rejected by an external authorization service.

  • RLSE: Request rejected because the rate-limiting service returned an error.

  • IH: Request rejected because a strictly-checked header contains an invalid value.

  • SI: Stream idle timeout.

  • DPE: HTTP protocol error in the downstream request.

  • UPE: HTTP protocol error in the upstream response.

  • UMSDR: The upstream request reached the maximum stream duration.

  • OM: The overload manager terminated the request.

Previous：View gateway monitoring dataNext：Enable tracing for an AI Gateway