| name | alibabacloud-apigw-inspection |
| description | Perform instance inspection on Alibaba Cloud Cloud-Native API Gateway, AI Gateway, and API Gateway, and query Cloud Monitor metric data. Use when the user needs to view monitoring metrics of gateway instances (such as CPU usage, memory usage, connections, network IO, bandwidth, rate limiting, etc.), obtain metric data for a specific point in time or time range, or evaluate resource utilization.
Trigger scenarios include: "check if the Cloud-Native API Gateway has enough resources", "view monitoring data of the AI Gateway instance", "inspect this API Gateway instance", "how is the gateway performing", "check if the gateway has any anomalies", "check gateway health status", etc.
|
Cloud-Native API Gateway / AI Gateway / API Gateway Instance Inspection
Scenario Description
Perform health inspection on Alibaba Cloud gateway instances, retrieve monitoring metric data, and generate inspection reports.
Architecture: Cloud Monitor (CMS) + API Gateway (cloudapi) + Cloud-Native API Gateway / AI Gateway (apig)
Supported Product Types:
| Product Type | Instance ID Format | Query Command |
|---|
| Cloud-Native API Gateway | gw-xxxxxxx | aliyun apig list-gateways |
| AI Gateway | gw-xxxxxxx | aliyun apig list-gateways |
| API Gateway (Dedicated) | apigateway-xx-xxxxxxx | aliyun cloudapi describe-instances |
Note: API Gateway shared instances (VPC_SHARED) do not support inspection. Only dedicated instances (VPC_DEDICATED) are supported.
Installation
Pre-check: Aliyun CLI >= 3.3.3 required
Run aliyun version to verify >= 3.3.3. If not installed or version too low,
follow the upgrade/installation instructions below.
Upgrade / Install Aliyun CLI (choose one based on your platform):
- macOS (Homebrew):
brew install aliyun-cli
brew upgrade aliyun-cli
- Linux / macOS (binary):
curl -fsSL https://aliyuncli.alicdn.com/setup.sh | bash
- Windows (PowerShell):
Invoke-WebRequest -Uri "https://aliyuncli.alicdn.com/aliyun-cli-windows-latest-amd64.zip" -OutFile "aliyun-cli.zip"
Expand-Archive -Path aliyun-cli.zip -DestinationPath C:\aliyun-cli
After upgrade, verify with aliyun version.
For more platforms and detailed instructions, see references/cli-installation-guide.md.
Pre-check: Aliyun CLI plugin update required
[MUST] run aliyun configure set --auto-plugin-install true to enable automatic plugin installation.
[MUST] run aliyun plugin update to ensure that any existing plugins are always up-to-date.
Observability (MUST follow for every aliyun command)
Upon loading this skill, generate a random session ID (32-char lowercase hex string) once
for the entire session. Use it as {session-id} below.
Rule: Every aliyun CLI command that calls a cloud API MUST include the --user-agent flag.
Local utility commands (e.g. configure, plugin, version) do not support this flag
and should be excluded.
--user-agent AlibabaCloud-Agent-Skills/alibabacloud-apigw-inspection/{session-id}
Environment Variables
No additional environment variables required. Credentials are configured via aliyun configure.
Authentication
Pre-check: Alibaba Cloud Credentials Required
Security Rules:
- NEVER read, echo, or print AK/SK values (e.g.,
echo $ALIBABA_CLOUD_ACCESS_KEY_ID is FORBIDDEN)
- NEVER ask the user to input AK/SK directly in the conversation or command line
- NEVER use
aliyun configure set with literal credential values
- ONLY use
aliyun configure list to check credential status
aliyun configure list
Check the output for a valid profile (AK, STS, or OAuth identity).
If no valid profile exists, STOP here.
- Obtain credentials from Alibaba Cloud Console
- Configure credentials outside of this session (via
aliyun configure in terminal or environment variables in shell profile)
- Return and re-run after
aliyun configure list shows a valid profile
RAM Permission Policy
This skill only involves read-only operations and requires the following minimum RAM permissions:
| Product | RAM Action | Description |
|---|
| API Gateway | apigateway:DescribeInstances | List API Gateway instances |
| API Gateway | apigateway:DescribeInstanceDropPacket | View dropped packet count |
| API Gateway | apigateway:DescribeInstanceDropConnections | View dropped connection count |
| API Gateway | apigateway:DescribeInstanceSlbConnect | View concurrent connection count |
| API Gateway | apigateway:DescribeInstanceTraffic | View traffic information |
| API Gateway | apigateway:DescribeInstanceQps | View QPS data |
| Cloud-Native API Gateway / AI Gateway | apig:ListGateways | Query gateway list |
| Cloud Monitor | cms:QueryMetricData | Query monitoring data |
Full policy document: references/ram-policies.md
[MUST] Permission Failure Handling: When any command or API call fails due to permission errors at any point during execution, follow this process:
- Read
references/ram-policies.md to get the full list of permissions required by this SKILL
- Use
ram-permission-diagnose skill to guide the user through requesting the necessary permissions
- Pause and wait until the user confirms that the required permissions have been granted
Parameter Confirmation
IMPORTANT: Parameter Confirmation — Before executing any command or API call,
ALL user-customizable parameters (e.g., RegionId, instance names, CIDR blocks,
passwords, domain names, resource specifications, etc.) MUST be confirmed with the
user. Do NOT assume or use default values without explicit user approval.
| Parameter | Required/Optional | Description | Default |
|---|
| Product Type | Required | Cloud-Native API Gateway / AI Gateway / API Gateway | None |
| RegionId | Required | Region where the instance is located | None |
| Instance ID | Required | Unique identifier of the gateway instance | None |
| Time Range | Optional | Query time point or time range | Current time |
Available Region Check:
Core Workflow
Step 1: Collect Required Information
Before starting queries, the following information must be confirmed (proactively ask the user if not provided). Using default configurations is prohibited:
- Cloud Product Type — Which cloud product the user wants to query.(Cloud-Native API Gateway / AI Gateway / API Gateway).
- Region (RegionId) — The region where the instance is located.
- Instance ID — The unique identifier of the instance.
- Time Range — The time point or time range for the query.
Step 2: Query Instance Information
[MUST] API Invocation Requirement:
The gateway list MUST be queried by calling the Apig ListGateways API via CLI plugin mode.
This is a mandatory step — skipping the gateway list query is NOT allowed.
[MUST] Plugin Mode Only:
All commands in this skill MUST be executed using CLI plugin mode. Traditional API format (PascalCase action names) is NOT allowed.
If the plugin is not installed, run aliyun plugin install --names apig to install it, then retry.
2.1 Cloud-Native API Gateway / AI Gateway
API Mapping: Product Apig | Action ListGateways | Version 2019-01-01
aliyun apig list-gateways --region ${region_id} \
--user-agent AlibabaCloud-Agent-Skills/alibabacloud-apigw-inspection/{session-id}
Note: The gatewayType in the response indicates the instance type: API (Cloud-Native API Gateway), AI (AI Gateway)
2.2 API Gateway
aliyun cloudapi describe-instances --api-version 2016-07-14 --region ${region_id} \
--user-agent AlibabaCloud-Agent-Skills/alibabacloud-apigw-inspection/{session-id}
Note: The InstanceType in the response indicates the instance type. Only VPC_DEDICATED (dedicated) instances are supported. VPC_SHARED shared instances do not support inspection.
Step 3: Retrieve Monitoring Metric Data
3.1 Cloud-Native API Gateway / AI Gateway
[MUST] API Invocation Requirement:
Monitoring metrics MUST be queried using the Cms DescribeMetricData API via CLI plugin mode
CRITICAL — PROHIBITED APIs:
- DO NOT USE
DescribeMetricList (aliyun cms describe-metric-list) — returns a different response format and is NOT accepted
- DO NOT USE
DescribeMetricMetaList (aliyun cms describe-metric-meta-list) — DO NOT call this API to discover or list available metrics
ALL metric names are already provided below. No metric discovery is needed:
- For Cloud-Native API Gateway instances: select metric names from the Supported Metrics for Cloud-Native API Gateway table below
- For AI Gateway instances: select metric names from the Supported Metrics for AI Gateway table below
- Use the exact
Metric Name values from the corresponding table directly as the --metric-name parameter
API Mapping: Product Cms | Action DescribeMetricData | Version 2019-01-01 | Namespace acs_cnapigateway
aliyun cms describe-metric-data \
--namespace acs_cnapigateway \
--region ${region} \
--api-version 2019-01-01 \
--metric-name ${metric-name} \
--period 60 \
--start-time ${start-time} \
--end-time ${end-time} \
--dimensions '[{"instanceId": "${instanceId}"}]' \
--user-agent AlibabaCloud-Agent-Skills/alibabacloud-apigw-inspection/{session-id}
Notes:
start-time / end-time use Unix millisecond timestampsinstanceId must be passed in dimensions- MUST query ALL of the following metric categories: CPU Usage, Memory Usage, Connections, Network IO, Rate Limiting
- Only check CPU, memory, connections, network IO, rate limiting, and bandwidth
Supported Metrics for Cloud-Native API Gateway:
| Metric Name | Display Name | Dimensions | Metric Period | Unit |
|---|
| EnvoyClientActiveConnection | Current active connections (gateway to client) | userId,regionId,instanceId | 60300 | count |
| EnvoyClientDestroyConnection | Destroyed connections per second (gateway to client) | userId,regionId,instanceId | 60300 | count/s |
| EnvoyClientDestroySSL | SSL handshake failures per second (gateway to client) | userId,regionId,instanceId | 60300 | count/s |
| EnvoyClientNewConnection | New connections per second (gateway to client) | userId,regionId,instanceId | 60300 | count/s |
| EnvoyClientNewSSL | SSL handshakes per second (gateway to client) | userId,regionId,instanceId | 60300 | count/s |
| EnvoyClientReuseSSL | SSL handshake reuse per second (gateway to client) | userId,regionId,instanceId | 60300 | count/s |
| EnvoyCpuUsageRate | Gateway CPU usage | userId,instanceId | 60300 | % |
| EnvoyFsReadBytes | Disk read load | userId,instanceId | 60300 | B/s |
| EnvoyFsWriteBytes | Disk write load | userId,instanceId | 60300 | B/s |
| EnvoyMemoryUsage | Memory load | userId,instanceId | 60300 | MiB |
| EnvoyMemoryUsageRate | Gateway memory usage | userId,instanceId | 60300 | % |
| EnvoyNetworkInBytes | Inbound network IO load | userId,instanceId | 60300 | B/s |
| EnvoyNetworkOutBytes | Outbound network IO load | userId,instanceId | 60300 | B/s |
| EnvoyRateLimitRequests | Rate-limited requests | userId,instanceId | 60300 | count/s |
| EnvoyUpstreamActiveConnection | Current active connections (gateway to backend) | userId,instanceId | 60300 | count |
| EnvoyUpstreamDestroyConnection | Destroyed connections per second (gateway to backend) | userId,instanceId | 60300 | count/s |
| EnvoyUpstreamNewConnection | New connections per second (gateway to backend) | userId,instanceId | 60300 | count/s |
| Ipv4EipRateIn | Public IPv4 inbound bandwidth | userId,instanceId | 60300 | bit/s |
| Ipv4EipRateOut | Public IPv4 outbound bandwidth | userId,instanceId | 60300 | bit/s |
| Ipv6GatewayRateIn | Public IPv6 inbound bandwidth | userId,instanceId | 60300 | bit/s |
| Ipv6GatewayRateOut | Public IPv6 outbound bandwidth | userId,instanceId | 60300 | bit/s |
| SlbInstanceTrafficRX | Private network inbound bandwidth | userId,instanceId | 60300 | bit/s |
| SlbInstanceTrafficTX | Private network outbound bandwidth | userId,instanceId | 60300 | bit/s |
Supported Metrics for AI Gateway:
| Metric Name | Display Name | Dimensions | Metric Period | Unit |
|---|
| AIGatewayEnvoyClientActiveConnection | Current active connections (gateway to client) | userId,regionId,instanceId | 60300 | count |
| AIGatewayEnvoyClientDestroyConnection | Destroyed connections per second (gateway to client) | userId,regionId,instanceId | 60300 | count/s |
| AIGatewayEnvoyClientDestroySSL | SSL handshake failures per second (gateway to client) | userId,regionId,instanceId | 60300 | count/s |
| AIGatewayEnvoyClientNewConnection | New connections per second (gateway to client) | userId,regionId,instanceId | 60300 | count/s |
| AIGatewayEnvoyClientNewSSL | SSL handshakes per second (gateway to client) | userId,regionId,instanceId | 60300 | count/s |
| AIGatewayEnvoyCpuUsageRate | Gateway CPU usage | userId,regionId,instanceId | 60300 | % |
| AIGatewayEnvoyFsReadBytes | Disk read load | userId,regionId,instanceId | 60300 | B/s |
| AIGatewayEnvoyFsWriteBytes | Disk write load | userId,regionId,instanceId | 60300 | B/s |
| AIGatewayEnvoyMemoryUsage | Memory load | userId,regionId,instanceId | 60300 | MiB |
| AIGatewayEnvoyMemoryUsageRate | Gateway memory usage | userId,regionId,instanceId | 60300 | % |
| AIGatewayEnvoyNetworkInBytes | Inbound network IO load | userId,regionId,instanceId | 60300 | B/s |
| AIGatewayEnvoyNetworkOutBytes | Outbound network IO load | userId,regionId,instanceId | 60300 | B/s |
| AIGatewayEnvoyRateLimitRequests | Rate-limited requests | userId,regionId,instanceId | 60300 | count/s |
| AIGatewayEnvoyUpstreamActiveConnection | Current active connections (gateway to backend) | userId,regionId,instanceId | 60300 | count |
| AIGatewayEnvoyUpstreamDestroyConnection | Destroyed connections per second (gateway to backend) | userId,regionId,instanceId | 60300 | count/s |
| AIGatewayEnvoyUpstreamNewConnection | New connections per second (gateway to backend) | userId,regionId,instanceId | 60300 | count/s |
| Ipv4EipRateIn | Public IPv4 inbound bandwidth | userId,instanceId | 60300 | bit/s |
| Ipv4EipRateOut | Public IPv4 outbound bandwidth | userId,instanceId | 60300 | bit/s |
| Ipv6GatewayRateIn | Public IPv6 inbound bandwidth | userId,instanceId | 60300 | bit/s |
| Ipv6GatewayRateOut | Public IPv6 outbound bandwidth | userId,instanceId | 60300 | bit/s |
| SlbInstanceTrafficRX | Private network inbound bandwidth | userId,instanceId | 60300 | bit/s |
| SlbInstanceTrafficTX | Private network outbound bandwidth | userId,instanceId | 60300 | bit/s |
3.2 API Gateway Dedicated Instances
[MUST] API Invocation Requirement:
For API Gateway dedicated instances, you MUST use the CloudAPI dedicated APIs via CLI plugin mode to query monitoring data.
DO NOT use Cloud Monitor (CMS) for API Gateway dedicated instances. CMS is only for Cloud-Native API Gateway / AI Gateway (Step 3.1).
The following 5 API calls are ALL mandatory:
| # | API | Product | Action | Version | Notes |
|---|
| 1 | Dropped packets | cloudapi | DescribeInstanceDropPacket | 2016-07-14 | |
| 2 | Dropped connections | cloudapi | DescribeInstanceDropConnections | 2016-07-14 | |
| 3 | SLB connections | cloudapi | DescribeInstanceSlbConnect | 2016-07-14 | |
| 4 | Traffic | cloudapi | DescribeInstanceTraffic | 2016-07-14 | Query RELEASE, PRE, TEST separately |
| 5 | QPS | cloudapi | DescribeInstanceQps | 2016-07-14 | Query RELEASE, PRE, TEST separately |
CRITICAL: Traffic and QPS must each be queried 3 times — once for each environment (RELEASE, PRE, TEST).
This means a total of 7 API calls (5 base APIs, but Traffic and QPS each × 3 environments).
Note: For API Gateway, skip 3.1 and execute this step directly. Time format uses ISO8601 UTC (YYYY-MM-DDThh:mm:ssZ)
aliyun cloudapi describe-instance-drop-packet \
--start-time ${start-time} --end-time ${end-time} \
--instance-id ${instanceId} --sbc-name Maximum \
--api-version 2016-07-14 --region ${region} \
--user-agent AlibabaCloud-Agent-Skills/alibabacloud-apigw-inspection/{session-id}
aliyun cloudapi describe-instance-drop-connections \
--start-time ${start-time} --end-time ${end-time} \
--instance-id ${instanceId} --sbc-name Maximum \
--api-version 2016-07-14 --region ${region} \
--user-agent AlibabaCloud-Agent-Skills/alibabacloud-apigw-inspection/{session-id}
aliyun cloudapi describe-instance-slb-connect \
--start-time ${start-time} --end-time ${end-time} \
--instance-id ${instanceId} --sbc-name Maximum \
--api-version 2016-07-14 --region ${region} \
--user-agent AlibabaCloud-Agent-Skills/alibabacloud-apigw-inspection/{session-id}
aliyun cloudapi describe-instance-traffic \
--start-time ${start-time} --end-time ${end-time} \
--instance-id ${instanceId} --stage-name RELEASE \
--api-version 2016-07-14 --region ${region} \
--user-agent AlibabaCloud-Agent-Skills/alibabacloud-apigw-inspection/{session-id}
aliyun cloudapi describe-instance-traffic \
--start-time ${start-time} --end-time ${end-time} \
--instance-id ${instanceId} --stage-name PRE \
--api-version 2016-07-14 --region ${region} \
--user-agent AlibabaCloud-Agent-Skills/alibabacloud-apigw-inspection/{session-id}
aliyun cloudapi describe-instance-traffic \
--start-time ${start-time} --end-time ${end-time} \
--instance-id ${instanceId} --stage-name TEST \
--api-version 2016-07-14 --region ${region} \
--user-agent AlibabaCloud-Agent-Skills/alibabacloud-apigw-inspection/{session-id}
aliyun cloudapi describe-instance-qps \
--start-time ${start-time} --end-time ${end-time} \
--instance-id ${instanceId} --stage-name RELEASE \
--api-version 2016-07-14 --region ${region} \
--user-agent AlibabaCloud-Agent-Skills/alibabacloud-apigw-inspection/{session-id}
aliyun cloudapi describe-instance-qps \
--start-time ${start-time} --end-time ${end-time} \
--instance-id ${instanceId} --stage-name PRE \
--api-version 2016-07-14 --region ${region} \
--user-agent AlibabaCloud-Agent-Skills/alibabacloud-apigw-inspection/{session-id}
aliyun cloudapi describe-instance-qps \
--start-time ${start-time} --end-time ${end-time} \
--instance-id ${instanceId} --stage-name TEST \
--api-version 2016-07-14 --region ${region} \
--user-agent AlibabaCloud-Agent-Skills/alibabacloud-apigw-inspection/{session-id}
Step 4: Generate Inspection Report
4.1 Anomaly Check Rules
| Metric | Normal | Warning | Critical |
|---|
| CPU Usage | < 70% | 70%-85% | > 85% |
| Memory Usage | < 75% | 75%-90% | > 90% |
| Connections | < 70% of max | 70%-85% | > 85% |
| Network IO | < 70% of bandwidth | 70%-85% | > 85% |
| Rate Limiting | No triggers | > 0 occurrences | Continuously increasing |
Spike Detection: Alert when the increase within a period exceeds the threshold (CPU > 30%, Memory > 25%, Connections > 50%, Network IO > 40%)
4.2 Report Structure
The inspection report should include the following sections:
- Basic Information — Product type, instance ID, region, inspection time
- Inspection Results Overview — Table format showing the status of each metric
- Detailed Analysis — Peak values, trends, and analysis for each metric
- Risk Assessment — List of high/medium risk items
- Optimization Recommendations — Recommendations based on actual issues (omit if all metrics are normal)
- Conclusion — Summary of inspection results
Important: All data must come from actual API responses. Fabricating data is strictly prohibited.
Success Verification
For verification methods, see references/verification-method.md
Cleanup
This skill only involves read-only operations. No resource cleanup is required.
Command List
For the full command list, see references/related-commands.md
Best Practices
- Plugin Mode Only: All commands MUST be executed using
aliyun CLI plugin mode. Traditional API format (PascalCase action names) is NOT allowed. If a required plugin is not installed, run aliyun plugin install --names <plugin-name> to install it first.
- Confirm Parameters: All user-customizable parameters must be confirmed before execution
- Check Region: Ensure the region is within the available regions for the corresponding product
- Check Instance Type: API Gateway only supports dedicated instance inspection
- Time Format: Cloud Monitor uses millisecond timestamps; API Gateway uses ISO8601 UTC
- Data Accuracy: Report data must come from actual API responses
- Risk Classification: Strictly follow threshold standards for risk assessment
Reference Links
