Alibaba Cloud EBS Disk Monitoring and Metric Analysis#

This skill enables you to query and analyze monitoring metrics for Alibaba Cloud Elastic Block Storage (EBS) disks. It supports querying single or multiple disks, performing time-series aggregation, and cross-disk metric analysis.

Scenario Description#

Monitor and analyze cloud disk performance metrics to:

• Track disk IOPS (read/write operations per second)
• Monitor disk bandwidth (BPS - bytes per second)
• Analyze disk performance trends over time
• Compare performance across multiple disks
• Aggregate metrics by disk type, instance, or availability zone
• Identify performance bottlenecks and optimization opportunities

Architecture: EBS Monitoring Service + Cloud Monitor + EBS Disks (System/Data Disks)

Supported Metrics:

• disk_bps_percent - Disk bandwidth utilization percentage
• disk_iops_percent - Disk IOPS utilization percentage
• disk_read_block_size - Average read block size
• disk_read_bps - Read bandwidth (bytes per second)
• disk_read_iops - Read IOPS
• disk_write_block_size - Average write block size
• disk_write_bps - Write bandwidth (bytes per second)
• disk_write_iops - Write IOPS

Aggregation Capabilities:

• Time Dimension: SUM, COUNT, AVG, MAX, MIN over time periods
• Cross-Disk Dimension: Aggregate metrics across multiple disks by SUM, AVG, COUNT, MAX, MIN
• Grouping: Group by DiskId, DeviceType, DeviceCategory, EcsInstanceId, or Availability Zone

---

Installation#

Pre-check: Aliyun CLI >= 3.3.3 required

Run aliyun version to verify >= 3.3.3. If not installed or version too low, run curl -fsSL https://aliyuncli.alicdn.com/setup.sh | bash to install/update, or see references/cli-installation-guide.md for installation instructions.

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.

---

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

bash

aliyun configure list

Check the output for a valid profile (AK, STS, or OAuth identity).

If no valid profile exists, STOP here.

1. Obtain credentials from Alibaba Cloud Console
2. Configure credentials outside of this session (via aliyun configure in terminal or environment variables in shell profile)
3. Return and re-run after aliyun configure list shows a valid profile

---

RAM Policy#

This skill requires the following Alibaba Cloud RAM permissions. See references/ram-policies.md for the complete permission policy.

Required API Permissions:

• ebs:DescribeMetricData - Query disk monitoring metrics

[MUST] Permission Failure Handling: When any command or API call fails due to permission errors at any point during execution, follow this process:

1. Read references/ram-policies.md to get the full list of permissions required by this SKILL
2. Use ram-permission-diagnose skill to guide the user through requesting the necessary permissions
3. 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, DiskId, MetricName, time ranges, aggregation methods, etc.) MUST be confirmed with the user. Do NOT assume or use default values without explicit user approval.

Required and Optional Parameters#

Parameter NameRequired/OptionalDescriptionDefault Value--metric-nameRequiredMetric to query (e.g., disk_read_iops, disk_write_bps)N/A--biz-region-idRequiredRegion ID (e.g., cn-hangzhou, cn-shanghai)N/A--start-timeOptionalQuery start time in ISO 8601 format (yyyy-MM-ddTHH:mm:ssZ)Last period if both start/end empty--end-timeOptionalQuery end time in ISO 8601 format (yyyy-MM-ddTHH:mm:ssZ)Current time--periodOptionalData granularity in seconds (5, 10, 60, 300, 600, 3600)5--dimensionsOptionalJSON filter for DiskId, DeviceType, DeviceCategory, EcsInstanceId, AzoneEmpty (all disks)--aggre-opsOptionalTime aggregation method (AVG_OVER_TIME, SUM_OVER_TIME, MAX_OVER_TIME, etc.)No aggregation--aggre-over-line-opsOptionalCross-disk aggregation (NON, SUM, AVG, COUNT, MAX, MIN)NON--group-by-labelsOptionalGroup by labels (DiskId, DeviceType, DeviceCategory, EcsInstanceId, Azone)No grouping

---

Core Workflow#

At the start of the Core Workflow (before any CLI invocation): [MUST] Enable AI-Mode — AI-mode is required for Agent Skill execution. Run the following commands before any CLI invocation:

bash

aliyun configure ai-mode enable
aliyun configure ai-mode set-user-agent --user-agent "AlibabaCloud-Agent-Skills/alibabacloud-ebs-disk-metric-analyzer"

Scenario 1: Query Single Disk Metrics#

Query read IOPS for a specific disk over the last hour:

bash

# Confirm with user: RegionId, DiskId, MetricName, time range
aliyun ebs describe-metric-data \
  --metric-name disk_read_iops \
  --start-time 2024-01-15T10:00:00Z \
  --end-time 2024-01-15T11:00:00Z \
  --period 60 \
  --dimensions "{\"DiskId\": [\"d-bp1234567890abcde\"]}" \
  --biz-region-id cn-hangzhou

Expected Output:

json

{
  "TotalCount": 1,
  "DataList": [
    {
      "Labels": "{\"DiskId\": \"d-bp1234567890abcde\"}",
      "Datapoints": "{\"1705315200\": 150, \"1705315260\": 148, \"1705315320\": 152, ...}"
    }
  ],
  "RequestId": "11B55F58-D3A4-4A9B-9596-342420D0****"
}

Scenario 2: Query Multiple Disks with Aggregation#

Query average write bandwidth across multiple data disks:

bash

# Confirm with user: RegionId, MetricName, DeviceType, aggregation method
aliyun ebs describe-metric-data \
  --metric-name disk_write_bps \
  --start-time 2024-01-15T09:00:00Z \
  --end-time 2024-01-15T10:00:00Z \
  --period 300 \
  --dimensions "{\"DeviceType\": [\"data\"]}" \
  --aggre-ops AVG_OVER_TIME \
  --aggre-over-line-ops AVG \
  --biz-region-id cn-shanghai

Scenario 3: Group Metrics by Disk Category#

Analyze IOPS utilization grouped by disk category (e.g., cloud_essd):

bash

# Confirm with user: RegionId, MetricName, grouping dimension
aliyun ebs describe-metric-data \
  --metric-name disk_iops_percent \
  --start-time 2024-01-15T00:00:00Z \
  --end-time 2024-01-15T23:59:59Z \
  --period 3600 \
  --aggre-ops MAX_OVER_TIME \
  --group-by-labels DeviceCategory \
  --biz-region-id cn-beijing

Scenario 4: Compare Performance Across Availability Zones#

Compare disk performance across different availability zones:

bash

# Confirm with user: RegionId, MetricName, grouping by Azone
aliyun ebs describe-metric-data \
  --metric-name disk_bps_percent \
  --start-time 2024-01-14T00:00:00Z \
  --end-time 2024-01-15T00:00:00Z \
  --period 600 \
  --aggre-ops AVG_OVER_TIME \
  --aggre-over-line-ops AVG \
  --group-by-labels Azone \
  --biz-region-id cn-hangzhou

Scenario 5: Multi-Dimension Filtering#

Query specific disks attached to specific ECS instances:

bash

# Confirm with user: RegionId, DiskIds, EcsInstanceId
aliyun ebs describe-metric-data \
  --metric-name disk_read_bps \
  --start-time 2024-01-15T12:00:00Z \
  --end-time 2024-01-15T13:00:00Z \
  --period 60 \
  --dimensions "{\"DiskId\": [\"d-bp11111\", \"d-bp22222\"], \"EcsInstanceId\": [\"i-bp1234567890\"]}" \
  --aggre-ops AVG_OVER_TIME \
  --biz-region-id cn-shenzhen

[MUST] Disable AI-Mode at EVERY exit point — Before delivering the final response for ANY reason, always disable AI-mode first. This applies to ALL exit paths: workflow success, workflow failure, error/exception, user cancellation, session end, or any other scenario where no further CLI commands will be executed. AI-mode is only used for Agent Skill invocation scenarios and MUST NOT remain enabled after the skill stops running.

bash

aliyun configure ai-mode disable

---

Success Verification Method#

After querying metrics, verify:

1. Response Status: Check that RequestId is present (indicates successful API call)
2. Data Presence: Verify DataList contains expected entries
3. Time Range: Confirm Datapoints timestamps match the requested time range
4. Metric Values: Validate metric values are within expected ranges (e.g., percentages 0-100)
5. No Warnings: Check that Warnings array is empty or review any warnings

For detailed verification steps, see references/verification-method.md.

---

Cleanup#

This skill only queries monitoring data and does not create any resources. No cleanup is required.

---

Best Practices#

1. Choose Appropriate Period: Use smaller periods (5s, 10s) for short-term analysis, larger periods (300s, 3600s) for long-term trends
2. Time Range Limits: Respect period-specific time range limits (e.g., 5s period supports max 12 hours)
3. Use Filters Wisely: Apply dimensions filters to reduce data volume and improve query performance
4. Aggregation Selection: Choose aggregation methods based on analysis goals (AVG for trends, MAX for peak detection, SUM for totals)
5. Group by Relevant Dimensions: Group by DeviceCategory to compare disk types, by Azone for regional analysis
6. Handle Warnings: Review the Warnings array if present - it may indicate incomplete data
7. Time Zone Awareness: All timestamps use UTC+0 (ISO 8601 format)
8. Batch Queries: For multiple disks, use array filters in dimensions instead of multiple API calls
9. Result Parsing: Parse JSON Datapoints field to extract timestamp-value pairs programmatically
10. Monitor Quota: Be aware of API rate limits when querying large time ranges or many disks

---

Reference Links#

Reference FileDescriptionreferences/ram-policies.mdComplete RAM permission policy for EBS monitoring APIsreferences/related-commands.mdAll EBS CLI commands used in this skillreferences/verification-method.mdDetailed verification steps and commandsreferences/acceptance-criteria.mdTest patterns and acceptance criteriareferences/cli-installation-guide.mdAlibaba Cloud CLI installation guide

---

Common Issues and Solutions#

Issue: "InvalidParameter: The parameter MetricName is invalid"

• Solution: Verify metric name matches one of the 8 supported metrics exactly (case-sensitive)

Issue: "InvalidParameter: Period exceeds time range limit"

• Solution: Reduce time range or increase period granularity (e.g., use 300s instead of 5s for longer ranges)

Issue: Empty DataList returned

• Solution: Check that disks exist in the specified region and match the dimension filters

Issue: Incomplete data warning

• Solution: Metrics may not be available for all time points; adjust time range or check disk activity during the period

---

Advanced Usage#

Using JMESPath Queries#

Filter output using --cli-query to extract specific data:

bash

# Extract only datapoints from first result
aliyun ebs describe-metric-data \
  --metric-name disk_read_iops \
  --dimensions "{\"DiskId\": [\"d-bp1234567890\"]}" \
  --biz-region-id cn-hangzhou \
  --cli-query "DataList[0].Datapoints"

Combining with Other Tools#

Pipe results to jq for advanced JSON processing:

bash

aliyun ebs describe-metric-data \
  --metric-name disk_write_bps \
  --dimensions "{\"DeviceType\": [\"data\"]}" \
  --biz-region-id cn-hangzhou \
  | jq '.DataList[].Datapoints | fromjson | to_entries | .[] | {timestamp: .key, value: .value}'

---

For more information:

• Alibaba Cloud EBS Documentation
• OpenAPI Explorer - DescribeMetricData