Alibabacloud Ebs Disk Metric Analyzer

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

---

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:

# 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:

{
  "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:

# 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):

# 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:

# 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:

# 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

---

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:

# 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:

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

Acceptance Criteria: alibabacloud-ebs-disk-metric-analyzer

Scenario: EBS Disk Monitoring and Metric Analysis Purpose: Skill testing acceptance criteria and validation patterns

---

Correct CLI Command Patterns

1. Product Name Verification

✅ CORRECT

aliyun ebs describe-metric-data --metric-name disk_read_iops

• Product name is ebs (lowercase)
• Product exists in Aliyun CLI

❌ INCORRECT

aliyun EBS describe-metric-data --metric-name disk_read_iops

• Error: Product names are case-sensitive and must be lowercase
• Fix: Use ebs not EBS

aliyun elastic-block-storage describe-metric-data --metric-name disk_read_iops

• Error: Product name is ebs, not the full service name
• Fix: Use ebs not elastic-block-storage

---

2. Command/Action Verification

✅ CORRECT

aliyun ebs describe-metric-data --metric-name disk_read_iops

• Action is describe-metric-data (plugin mode: lowercase with hyphens)
• Matches the API DescribeMetricData (PascalCase converted to kebab-case)

❌ INCORRECT

aliyun ebs DescribeMetricData --metric-name disk_read_iops

• Error: Using API-style PascalCase instead of plugin mode kebab-case
• Fix: Use describe-metric-data not DescribeMetricData

aliyun ebs get-metric-data --metric-name disk_read_iops

• Error: Action name does not exist
• Fix: Use describe-metric-data not get-metric-data

aliyun ebs query-metric-data --metric-name disk_read_iops

• Error: Action name does not exist
• Fix: Use describe-metric-data not query-metric-data

---

3. Required Parameter Verification

✅ CORRECT

aliyun ebs describe-metric-data \
  --metric-name disk_read_iops \
  --biz-region-id cn-hangzhou

• --metric-name is present (required parameter)
• Valid metric name from the allowed list

❌ INCORRECT

aliyun ebs describe-metric-data --biz-region-id cn-hangzhou

• Error: Missing required parameter --metric-name
• Fix: Add --metric-name with a valid metric name

aliyun ebs describe-metric-data --metric disk_read_iops

• Error: Parameter name is --metric-name not --metric
• Fix: Use --metric-name not --metric

---

4. Parameter Name Verification

✅ CORRECT

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-bp1234567890\"]}" \
  --aggre-ops AVG_OVER_TIME \
  --aggre-over-line-ops AVG \
  --group-by-labels DiskId \
  --biz-region-id cn-hangzhou

• All parameter names match --help output exactly
• Uses kebab-case (hyphens between words)

❌ INCORRECT

aliyun ebs describe-metric-data \
  --metric-name disk_read_iops \
  --startTime 2024-01-15T10:00:00Z \
  --endTime 2024-01-15T11:00:00Z

• Error: Using camelCase parameter names instead of kebab-case
• Fix: Use --start-time and --end-time, not --startTime and --endTime

aliyun ebs describe-metric-data \
  --metric-name disk_read_iops \
  --region-id cn-hangzhou

• Error: Parameter is --biz-region-id not --region-id
• Fix: Use --biz-region-id

aliyun ebs describe-metric-data \
  --metric-name disk_read_iops \
  --dimension "{\"DiskId\": [\"d-bp1234567890\"]}"

• Error: Parameter is --dimensions (plural) not --dimension
• Fix: Use --dimensions with an 's'

aliyun ebs describe-metric-data \
  --metric-name disk_read_iops \
  --aggregation AVG_OVER_TIME

• Error: Parameter is --aggre-ops not --aggregation
• Fix: Use --aggre-ops for time aggregation

aliyun ebs describe-metric-data \
  --metric-name disk_read_iops \
  --group-by DiskId

• Error: Parameter is --group-by-labels not --group-by
• Fix: Use --group-by-labels

---

5. Metric Name Values

✅ CORRECT

aliyun ebs describe-metric-data --metric-name disk_read_iops
aliyun ebs describe-metric-data --metric-name disk_write_bps
aliyun ebs describe-metric-data --metric-name disk_bps_percent
aliyun ebs describe-metric-data --metric-name disk_iops_percent
aliyun ebs describe-metric-data --metric-name disk_read_block_size
aliyun ebs describe-metric-data --metric-name disk_write_block_size

• All values are from the 8 allowed metric names
• Exact case-sensitive match

❌ INCORRECT

aliyun ebs describe-metric-data --metric-name DISK_READ_IOPS

• Error: Metric names are case-sensitive (lowercase)
• Fix: Use disk_read_iops not DISK_READ_IOPS

aliyun ebs describe-metric-data --metric-name disk_iops

• Error: Metric name does not exist
• Fix: Use disk_read_iops or disk_write_iops or disk_iops_percent

aliyun ebs describe-metric-data --metric-name read_iops

• Error: Metric name does not exist
• Fix: Use disk_read_iops (includes "disk_" prefix)

---

6. Time Format Verification

✅ CORRECT

aliyun ebs describe-metric-data \
  --metric-name disk_read_iops \
  --start-time 2024-01-15T10:00:00Z \
  --end-time 2024-01-15T11:00:00Z

• ISO 8601 format: yyyy-MM-ddTHH:mm:ssZ
• Uses UTC+0 timezone (Z suffix)

❌ INCORRECT

aliyun ebs describe-metric-data \
  --metric-name disk_read_iops \
  --start-time "2024-01-15 10:00:00"

• Error: Not ISO 8601 format (missing 'T' separator and 'Z' timezone)
• Fix: Use 2024-01-15T10:00:00Z

aliyun ebs describe-metric-data \
  --metric-name disk_read_iops \
  --start-time 1705315200

• Error: Unix timestamp not accepted (requires ISO 8601 string)
• Fix: Convert to 2024-01-15T10:00:00Z

aliyun ebs describe-metric-data \
  --metric-name disk_read_iops \
  --start-time 2024-01-15T10:00:00+08:00

• Error: Must use UTC+0 (Z), not other timezones
• Fix: Convert to UTC and use 2024-01-15T02:00:00Z

---

7. Period Value Verification

✅ CORRECT

aliyun ebs describe-metric-data --metric-name disk_read_iops --period 5
aliyun ebs describe-metric-data --metric-name disk_read_iops --period 10
aliyun ebs describe-metric-data --metric-name disk_read_iops --period 60
aliyun ebs describe-metric-data --metric-name disk_read_iops --period 300
aliyun ebs describe-metric-data --metric-name disk_read_iops --period 600
aliyun ebs describe-metric-data --metric-name disk_read_iops --period 3600

• All values are from the allowed list: 5, 10, 60, 300, 600, 3600

❌ INCORRECT

aliyun ebs describe-metric-data --metric-name disk_read_iops --period 30

• Error: 30 is not an allowed period value
• Fix: Use 60 (closest allowed value)

aliyun ebs describe-metric-data --metric-name disk_read_iops --period 1800

• Error: 1800 is not an allowed period value
• Fix: Use 600 or 3600

aliyun ebs describe-metric-data --metric-name disk_read_iops --period "60s"

• Error: Period must be integer, not string with unit
• Fix: Use 60 not "60s"

---

8. Dimensions JSON Format

✅ CORRECT

aliyun ebs describe-metric-data \
  --metric-name disk_read_iops \
  --dimensions "{\"DiskId\": [\"d-bp1234567890\"]}"

aliyun ebs describe-metric-data \
  --metric-name disk_read_iops \
  --dimensions "{\"DiskId\": [\"d-bp111\", \"d-bp222\"], \"DeviceType\": [\"data\"]}"

aliyun ebs describe-metric-data \
  --metric-name disk_read_iops \
  --dimensions "{\"DeviceCategory\": [\"cloud_essd\"]}"

• JSON format with escaped quotes in shell
• Array values (even for single item)
• Valid dimension keys: DiskId, DeviceType, DeviceCategory, EcsInstanceId, Azone

❌ INCORRECT

aliyun ebs describe-metric-data \
  --metric-name disk_read_iops \
  --dimensions '{"DiskId": "d-bp1234567890"}'

• Error: Value must be array, not string
• Fix: Use {"DiskId": ["d-bp1234567890"]}

aliyun ebs describe-metric-data \
  --metric-name disk_read_iops \
  --dimensions {"DiskId": ["d-bp1234567890"]}

• Error: JSON must be quoted in shell
• Fix: Use "{\"DiskId\": [\"d-bp1234567890\"]}"

aliyun ebs describe-metric-data \
  --metric-name disk_read_iops \
  --dimensions "{\"disk_id\": [\"d-bp1234567890\"]}"

• Error: Dimension key is case-sensitive (should be DiskId not disk_id)
• Fix: Use DiskId (PascalCase)

aliyun ebs describe-metric-data \
  --metric-name disk_read_iops \
  --dimensions "{\"VolumeId\": [\"d-bp1234567890\"]}"

• Error: Invalid dimension key (VolumeId not supported)
• Fix: Use DiskId, not VolumeId

---

9. Aggregation Operator Values

✅ CORRECT

# Time aggregation
aliyun ebs describe-metric-data --metric-name disk_read_iops --aggre-ops AVG_OVER_TIME
aliyun ebs describe-metric-data --metric-name disk_read_iops --aggre-ops SUM_OVER_TIME
aliyun ebs describe-metric-data --metric-name disk_read_iops --aggre-ops MAX_OVER_TIME
aliyun ebs describe-metric-data --metric-name disk_read_iops --aggre-ops MIN_OVER_TIME
aliyun ebs describe-metric-data --metric-name disk_read_iops --aggre-ops COUNT_OVER_TIME

# Cross-disk aggregation
aliyun ebs describe-metric-data --metric-name disk_read_iops --aggre-over-line-ops AVG
aliyun ebs describe-metric-data --metric-name disk_read_iops --aggre-over-line-ops SUM
aliyun ebs describe-metric-data --metric-name disk_read_iops --aggre-over-line-ops MAX
aliyun ebs describe-metric-data --metric-name disk_read_iops --aggre-over-line-ops MIN
aliyun ebs describe-metric-data --metric-name disk_read_iops --aggre-over-line-ops COUNT
aliyun ebs describe-metric-data --metric-name disk_read_iops --aggre-over-line-ops NON

• All values match allowed enum values exactly

❌ INCORRECT

aliyun ebs describe-metric-data --metric-name disk_read_iops --aggre-ops AVERAGE

• Error: Use AVG_OVER_TIME not AVERAGE
• Fix: Use one of the allowed values: SUM_OVER_TIME, COUNT_OVER_TIME, AVG_OVER_TIME, MAX_OVER_TIME, MIN_OVER_TIME

aliyun ebs describe-metric-data --metric-name disk_read_iops --aggre-over-line-ops NONE

• Error: Use NON not NONE
• Fix: Use NON for no aggregation

aliyun ebs describe-metric-data --metric-name disk_read_iops --aggre-ops avg_over_time

• Error: Values are case-sensitive (must be uppercase)
• Fix: Use AVG_OVER_TIME not avg_over_time

---

10. Group By Labels Values

✅ CORRECT

aliyun ebs describe-metric-data \
  --metric-name disk_read_iops \
  --group-by-labels DiskId

aliyun ebs describe-metric-data \
  --metric-name disk_read_iops \
  --group-by-labels DeviceType

aliyun ebs describe-metric-data \
  --metric-name disk_read_iops \
  --group-by-labels DeviceCategory

aliyun ebs describe-metric-data \
  --metric-name disk_read_iops \
  --group-by-labels EcsInstanceId

aliyun ebs describe-metric-data \
  --metric-name disk_read_iops \
  --group-by-labels Azone

# Multiple labels (space-separated)
aliyun ebs describe-metric-data \
  --metric-name disk_read_iops \
  --group-by-labels DiskId DeviceType

• Valid label names: DiskId, DeviceType, DeviceCategory, EcsInstanceId, Azone
• Multiple labels separated by spaces (not commas)

❌ INCORRECT

aliyun ebs describe-metric-data \
  --metric-name disk_read_iops \
  --group-by-labels disk_id

• Error: Label names are case-sensitive (PascalCase)
• Fix: Use DiskId not disk_id

aliyun ebs describe-metric-data \
  --metric-name disk_read_iops \
  --group-by-labels InstanceId

• Error: Label name is EcsInstanceId not InstanceId
• Fix: Use EcsInstanceId

aliyun ebs describe-metric-data \
  --metric-name disk_read_iops \
  --group-by-labels "DiskId,DeviceType"

• Error: Multiple labels should be space-separated, not comma-separated
• Fix: Use --group-by-labels DiskId DeviceType

aliyun ebs describe-metric-data \
  --metric-name disk_read_iops \
  --group-by-labels Region

• Error: Region is not a valid group-by label
• Fix: Use one of: DiskId, DeviceType, DeviceCategory, EcsInstanceId, Azone

---

11. Region ID Format

✅ CORRECT

aliyun ebs describe-metric-data --metric-name disk_read_iops --biz-region-id cn-hangzhou
aliyun ebs describe-metric-data --metric-name disk_read_iops --biz-region-id cn-shanghai
aliyun ebs describe-metric-data --metric-name disk_read_iops --biz-region-id cn-beijing
aliyun ebs describe-metric-data --metric-name disk_read_iops --biz-region-id ap-southeast-1
aliyun ebs describe-metric-data --metric-name disk_read_iops --biz-region-id us-west-1

• Valid Alibaba Cloud region IDs
• Format: {area}-{location} or {area}-{location}-{number}

❌ INCORRECT

aliyun ebs describe-metric-data --metric-name disk_read_iops --biz-region-id hangzhou

• Error: Missing country prefix
• Fix: Use cn-hangzhou not hangzhou

aliyun ebs describe-metric-data --metric-name disk_read_iops --biz-region-id cn_hangzhou

• Error: Region IDs use hyphens, not underscores
• Fix: Use cn-hangzhou not cn_hangzhou

---

Response Validation Patterns

1. Successful Response Structure

✅ CORRECT Response

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

• Contains RequestId (always present on success)
• TotalCount matches DataList length
• Labels is JSON string (needs parsing)
• Datapoints is JSON string with timestamp-value pairs

❌ INCORRECT Interpretation

{
  "Code": "InvalidParameter",
  "Message": "The parameter MetricName is invalid."
}

• Error: This is an error response, not success
• Check: Verify metric name is from allowed list

---

2. Empty Results vs. Errors

✅ CORRECT (Empty but Valid)

{
  "TotalCount": 0,
  "DataList": [],
  "RequestId": "11B55F58-D3A4-4A9B-9596-342420D0****"
}

• Valid response with no data (disk doesn't exist or no activity)

❌ ERROR Response

{
  "Code": "Forbidden",
  "Message": "User is not authorized to operate."
}

• Permission error - check RAM policies

---

Common Error Patterns and Fixes

---

Testing Checklist

Before considering the skill complete, verify:

• [ ] Command uses plugin mode format (describe-metric-data, not DescribeMetricData)
• [ ] Product name is lowercase (ebs)
• [ ] All parameter names match --help output exactly
• [ ] Required parameter --metric-name is present
• [ ] Metric names are from allowed list of 8 metrics
• [ ] Time format is ISO 8601 with UTC+0 (Z suffix)
• [ ] Period values are from allowed list (5, 10, 60, 300, 600, 3600)
• [ ] Dimensions JSON uses escaped quotes and array values
• [ ] Dimension keys are PascalCase (DiskId, not disk_id)
• [ ] Aggregation operators match allowed enum values exactly
• [ ] Group-by labels are PascalCase and space-separated
• [ ] Region IDs use standard Alibaba Cloud format
• [ ] Response contains RequestId on success
• [ ] Empty DataList is handled gracefully

---

Reference

• Alibaba Cloud CLI Documentation
• EBS DescribeMetricData API
• Command verification: aliyun ebs describe-metric-data --help

Aliyun CLI Installation & Configuration Guide

Complete guide for installing and configuring Aliyun CLI.

Aliyun CLI 3.3.3+: Supports installing and using all published Alibaba Cloud product plugins. Make sure to upgrade to 3.3.3 or later for full plugin ecosystem coverage.

Installation

macOS

Using Homebrew (Recommended)

brew install aliyun-cli
# Upgrade to latest
brew upgrade aliyun-cli

# Verify version (>= 3.3.3)
aliyun version

Using Binary

# Download
wget https://aliyuncli.alicdn.com/aliyun-cli-macosx-latest-amd64.tgz

# Extract
tar -xzf aliyun-cli-macosx-latest-amd64.tgz

# Move to PATH
sudo mv aliyun /usr/local/bin/

# Verify
aliyun version

Linux

Debian/Ubuntu

# Download
wget https://aliyuncli.alicdn.com/aliyun-cli-linux-latest-amd64.tgz

# Extract and install
tar -xzf aliyun-cli-linux-latest-amd64.tgz
sudo mv aliyun /usr/local/bin/

# Verify
aliyun version

CentOS/RHEL

# Download
wget https://aliyuncli.alicdn.com/aliyun-cli-linux-latest-amd64.tgz

# Extract and install
tar -xzf aliyun-cli-linux-latest-amd64.tgz
sudo mv aliyun /usr/local/bin/

# Verify
aliyun version

ARM64 Architecture

# Download ARM64 version
wget https://aliyuncli.alicdn.com/aliyun-cli-linux-latest-arm64.tgz

# Extract and install
tar -xzf aliyun-cli-linux-latest-arm64.tgz
sudo mv aliyun /usr/local/bin/

Windows

Using Binary 1. Download from: https://aliyuncli.alicdn.com/aliyun-cli-windows-latest-amd64.zip 2. Extract the ZIP file 3. Add the directory to your PATH environment variable 4. Open new Command Prompt or PowerShell 5. Verify: aliyun version

Using PowerShell

# Download
Invoke-WebRequest -Uri "https://aliyuncli.alicdn.com/aliyun-cli-windows-latest-amd64.zip" -OutFile "aliyun-cli.zip"

# Extract
Expand-Archive -Path aliyun-cli.zip -DestinationPath C:\aliyun-cli

# Add to PATH (requires admin privileges)
$env:Path += ";C:\aliyun-cli"
[Environment]::SetEnvironmentVariable("Path", $env:Path, [System.EnvironmentVariableTarget]::Machine)

# Verify
aliyun version

Configuration

Quick Start

aliyun configure set \
  --mode AK \
  --access-key-id <your-access-key-id> \
  --access-key-secret <your-access-key-secret> \
  --region cn-hangzhou

All aliyun configure commands support non-interactive flags, which is the recommended approach — it works in scripts, CI/CD pipelines, and agent-driven automation without hanging on stdin prompts.

Where to Get Access Keys

1. Log in to Aliyun Console: https://ram.console.aliyun.com/ 2. Navigate to: AccessKey Management 3. Create a new AccessKey pair 4. Save the secret immediately — it's only shown once

Configuration Modes

Aliyun CLI supports 6 authentication modes. All examples below use non-interactive flags.

1. AK Mode (Access Key)

Most common mode for personal accounts and scripts.

aliyun configure set \
  --mode AK \
  --access-key-id LTAI5tXXXXXXXX \
  --access-key-secret 8dXXXXXXXXXXXXXXXXXXXXXXXX \
  --region cn-hangzhou

Configuration is stored in ~/.aliyun/config.json:

{
  "current": "default",
  "profiles": [
    {
      "name": "default",
      "mode": "AK",
      "access_key_id": "LTAI5tXXXXXXXX",
      "access_key_secret": "8dXXXXXXXXXXXXXXXXXXXXXXXX",
      "region_id": "cn-hangzhou",
      "output_format": "json",
      "language": "en"
    }
  ]
}

2. StsToken Mode (Temporary Credentials)

For short-lived access (tokens expire in 1-12 hours).

aliyun configure set \
  --mode StsToken \
  --access-key-id LTAI5tXXXXXXXX \
  --access-key-secret 8dXXXXXXXXXXXXXXXXXXXXXXXX \
  --sts-token v1.0:XXXXXXXXXXXXXXXX \
  --region cn-hangzhou

Use cases: CI/CD pipelines, temporary access for external contractors, cross-account access.

3. RamRoleArn Mode (Assume RAM Role)

Assume a RAM role for elevated or cross-account access.

aliyun configure set \
  --mode RamRoleArn \
  --access-key-id LTAI5tXXXXXXXX \
  --access-key-secret 8dXXXXXXXXXXXXXXXXXXXXXXXX \
  --ram-role-arn acs:ram::123456789012:role/AdminRole \
  --role-session-name my-session \
  --region cn-hangzhou

Use cases: cross-account resource access, temporary elevated privileges, role-based access control.

4. EcsRamRole Mode (ECS Instance RAM Role)

Use the RAM role attached to an ECS instance — no credentials needed.

aliyun configure set \
  --mode EcsRamRole \
  --ram-role-name MyEcsRole \
  --region cn-hangzhou

Requirements: must be running on an ECS instance with a RAM role attached.

Use cases: scripts and automation running on ECS instances.

5. RsaKeyPair Mode (RSA Key Pair)

Use RSA key pair for authentication (generate key pair in Aliyun Console first).

aliyun configure set \
  --mode RsaKeyPair \
  --private-key /path/to/private-key.pem \
  --key-pair-name my-key-pair \
  --region cn-hangzhou

6. RamRoleArnWithEcs Mode (ECS + RAM Role)

Combine ECS instance role with RAM role assumption for cross-account access from ECS.

aliyun configure set \
  --mode RamRoleArnWithEcs \
  --ram-role-name MyEcsRole \
  --ram-role-arn acs:ram::123456789012:role/TargetRole \
  --role-session-name my-session \
  --region cn-hangzhou

Environment Variables

Highest priority - overrides config file

Access Key Mode

export ALIBABA_CLOUD_ACCESS_KEY_ID=your_access_key_id
export ALIBABA_CLOUD_ACCESS_KEY_SECRET=your_access_key_secret
export ALIBABA_CLOUD_REGION_ID=cn-hangzhou

STS Token Mode

export ALIBABA_CLOUD_ACCESS_KEY_ID=your_access_key_id
export ALIBABA_CLOUD_ACCESS_KEY_SECRET=your_access_key_secret
export ALIBABA_CLOUD_SECURITY_TOKEN=your_sts_token
export ALIBABA_CLOUD_REGION_ID=cn-hangzhou

ECS RAM Role Mode

export ALIBABA_CLOUD_ECS_METADATA=role_name

Use Case:

• CI/CD pipelines
• Docker containers
• Temporary credential override

Managing Multiple Profiles

Create Named Profiles

aliyun configure set --profile projectA \
  --mode AK \
  --access-key-id LTAI5tAAAAAAAA \
  --access-key-secret 8dAAAAAAAAAAAAAAAAAAAAAAAA \
  --region cn-hangzhou

aliyun configure set --profile projectB \
  --mode AK \
  --access-key-id LTAI5tBBBBBBBB \
  --access-key-secret 8dBBBBBBBBBBBBBBBBBBBBBBBB \
  --region cn-shanghai

Use Specific Profile

aliyun ecs describe-instances --profile projectA

export ALIBABA_CLOUD_PROFILE=projectA
aliyun ecs describe-instances   # Uses projectA

List and Switch Profiles

aliyun configure list                      # List all profiles
aliyun configure set --current projectA    # Switch default profile

Credential Priority

Credentials are loaded in this order (first found wins):

1. Command-line flag: --profile <name> 2. Environment variable: ALIBABA_CLOUD_PROFILE 3. Environment credentials: ALIBABA_CLOUD_ACCESS_KEY_ID, etc. 4. Configuration file: ~/.aliyun/config.json (current profile) 5. ECS Instance RAM Role: If running on ECS with attached role

Verification

Test Authentication

# Basic test - list regions
aliyun ecs describe-regions

# Expected output: JSON array of regions

If successful, you'll see:

{
  "Regions": {
    "Region": [
      {
        "RegionId": "cn-hangzhou",
        "RegionEndpoint": "ecs.cn-hangzhou.aliyuncs.com",
        "LocalName": "华东 1（杭州）"
      },
      ...
    ]
  },
  "RequestId": "..."
}

If failed, you'll see error messages:

• InvalidAccessKeyId.NotFound - Wrong Access Key ID
• SignatureDoesNotMatch - Wrong Access Key Secret
• InvalidSecurityToken.Expired - STS token expired (for StsToken mode)
• Forbidden.RAM - Insufficient permissions

Debug Configuration

# Show current configuration
aliyun configure get

# Test with debug logging
aliyun ecs describe-regions --log-level=debug

# Check credential provider
aliyun configure get mode

Security Best Practices

1. Use RAM Users (Not Root Account)

❌ Don't: Use Aliyun root account credentials ✅ Do: Create RAM users with specific permissions

# Create RAM user in console
# Attach only necessary policies
# Use RAM user's access keys

2. Principle of Least Privilege

Grant only the minimum permissions needed:

# Example: Read-only ECS access
# Attach policy: AliyunECSReadOnlyAccess

3. Rotate Access Keys Regularly

# Create new access key in RAM Console, then update configuration
aliyun configure set --access-key-id NEW_KEY --access-key-secret NEW_SECRET
# Delete old access key from console

4. Use STS Tokens for Temporary Access

aliyun configure set --mode StsToken \
  --access-key-id XXXX --access-key-secret XXXX \
  --sts-token XXXX --region cn-hangzhou

5. Use ECS RAM Roles When Possible

aliyun configure set --mode EcsRamRole --ram-role-name MyRole --region cn-hangzhou

6. Never Commit Credentials

# Add to .gitignore
echo "~/.aliyun/config.json" >> .gitignore

# Use environment variables in CI/CD instead

7. Secure Config File

# Restrict permissions
chmod 600 ~/.aliyun/config.json

Troubleshooting

Issue: Command Not Found

# Check installation
which aliyun

# Check PATH
echo $PATH

# Reinstall or add to PATH

Issue: Authentication Failed

# Verify configuration
aliyun configure get

# Test with debug
aliyun ecs describe-regions --log-level=debug

# Check credentials in console
# Verify access key is active

Issue: Permission Denied

# Error: Forbidden.RAM

# Check RAM user permissions
# Attach necessary policies in RAM console
# Example: AliyunECSFullAccess for ECS operations

Issue: STS Token Expired

# Error: InvalidSecurityToken.Expired

# Reconfigure with new token
aliyun configure set --mode StsToken \
  --access-key-id XXXX --access-key-secret XXXX \
  --sts-token NEW_TOKEN --region cn-hangzhou

Issue: Wrong Region

# Some resources may not exist in the specified region

# Check available regions
aliyun ecs describe-regions

# Update default region
aliyun configure set region cn-shanghai

Advanced Configuration

Custom Endpoint

# Use custom or private endpoint
export ALIBABA_CLOUD_ECS_ENDPOINT=ecs-vpc.cn-hangzhou.aliyuncs.com

Proxy Settings

# HTTP proxy
export HTTP_PROXY=http://proxy.example.com:8080
export HTTPS_PROXY=http://proxy.example.com:8080

# No proxy for specific domains
export NO_PROXY=localhost,127.0.0.1,.aliyuncs.com

Timeout Settings

# Connection timeout (default: 10s)
export ALIBABA_CLOUD_CONNECT_TIMEOUT=30

# Read timeout (default: 10s)
export ALIBABA_CLOUD_READ_TIMEOUT=30

Next Steps

After installation and configuration:

1. Install plugins for services you need (v3.3.3+ supports all published product plugins):

   aliyun plugin install --names ecs vpc rds

   # List all available plugins
   aliyun plugin list-remote

2. Explore commands:

   aliyun ecs --help
   aliyun fc --help

3. Read documentation:

• Command Syntax Guide
• Global Flags Reference
• Common Scenarios

References

• Official Documentation: https://help.aliyun.com/zh/cli/
• RAM Console: https://ram.console.aliyun.com/
• Access Key Management: https://ram.console.aliyun.com/manage/ak
• Plugin Repository: https://github.com/aliyun/aliyun-cli

RAM Policies for EBS Disk Monitoring and Metric Analysis

This document lists all RAM (Resource Access Management) permissions required for the alibabacloud-ebs-disk-metric-analyzer skill.

---

Required Permissions

The following permissions are required to execute all operations in this skill:

---

Minimum RAM Policy

Below is the minimum RAM policy required for this skill to function:

{
  "Version": "1",
  "Statement": [
    {
      "Effect": "Allow",
      "Action": [
        "ebs:DescribeMetricData"
      ],
      "Resource": "*"
    }
  ]
}

---

Creating a Custom RAM Policy

Via Alibaba Cloud Console

1. Log in to the RAM Console 2. Navigate to Permissions > Policies 3. Click Create Policy 4. Select JSON tab 5. Paste the minimum RAM policy above 6. Name the policy (e.g., EBSDiskMetricAnalyzerPolicy) 7. Click OK to create

Via Aliyun CLI

# Create policy file
cat > ebs-metric-policy.json <<EOF
{
  "Version": "1",
  "Statement": [
    {
      "Effect": "Allow",
      "Action": [
        "ebs:DescribeMetricData"
      ],
      "Resource": "*"
    }
  ]
}
EOF

# Create the RAM policy
aliyun ram create-policy \
  --policy-name EBSDiskMetricAnalyzerPolicy \
  --policy-document "$(cat ebs-metric-policy.json)" \
  --description "Policy for EBS disk monitoring and metric analysis"

# Attach policy to a user (replace YOUR_USER_NAME)
aliyun ram attach-policy-to-user \
  --policy-name EBSDiskMetricAnalyzerPolicy \
  --policy-type Custom \
  --user-name YOUR_USER_NAME

---

Resource-Level Permissions

The ebs:DescribeMetricData API currently requires "Resource": "*" as it queries metrics across multiple disks and does not support resource-level authorization.

---

Permission Verification

To verify that your current credentials have the required permissions:

# Test the DescribeMetricData API with a simple query
aliyun ebs describe-metric-data \
  --metric-name disk_read_iops \
  --biz-region-id cn-hangzhou \
  --period 60

Expected Success: Returns monitoring data or an empty DataList (if no disks exist).

Permission Denied Error:

{
  "Code": "Forbidden",
  "Message": "User is not authorized to operate."
}

If you receive a permission error: 1. Review this document to confirm required permissions 2. Use the ram-permission-diagnose skill to troubleshoot 3. Contact your account administrator to grant the necessary permissions

---

Additional Permissions for Advanced Usage

If you plan to extend this skill with additional EBS operations, consider these permissions:

---

Troubleshooting Permission Issues

Common Error Codes

Debug Steps

1. Verify credentials are configured:

   aliyun configure list

2. Check user permissions:

   aliyun ram list-policies-for-user --user-name YOUR_USER_NAME

3. Verify policy contains required actions:

   aliyun ram get-policy --policy-name EBSDiskMetricAnalyzerPolicy --policy-type Custom

---

Security Best Practices

1. Principle of Least Privilege: Only grant ebs:DescribeMetricData if users only need to query metrics 2. Use RAM Roles: For ECS instances or container environments, use RAM roles instead of AccessKey credentials 3. Rotate Credentials: Regularly rotate AccessKey pairs 4. Enable MFA: Enable multi-factor authentication for sensitive operations 5. Audit Logs: Enable ActionTrail to monitor API calls and permission usage

---

Reference

• Alibaba Cloud RAM Documentation
• EBS API Authorization
• RAM Policy Elements

Related CLI Commands

This document lists all Alibaba Cloud CLI commands used in the alibabacloud-ebs-disk-metric-analyzer skill.

---

EBS (Elastic Block Storage) Commands

Core Command

---

Command Details

aliyun ebs describe-metric-data

Query single or multiple disk monitoring metrics with optional aggregation and grouping.

Usage:

aliyun ebs describe-metric-data [parameters]

Required Parameters:

• --metric-name (string) - Metric name to query

Optional Parameters:

• --biz-region-id (string) - Region ID (e.g., cn-hangzhou)
• --start-time (string) - Query start time (ISO 8601 format: yyyy-MM-ddTHH:mm:ssZ)
• --end-time (string) - Query end time (ISO 8601 format: yyyy-MM-ddTHH:mm:ssZ)
• --period (integer) - Data granularity in seconds (5, 10, 60, 300, 600, 3600)
• --dimensions (string) - JSON filter for disk dimensions
• --aggre-ops (string) - Time aggregation method
• --aggre-over-line-ops (string) - Cross-disk aggregation method
• --group-by-labels (array) - Fields for grouping

Supported Metric Names: 1. disk_bps_percent - Disk bandwidth utilization percentage 2. disk_iops_percent - Disk IOPS utilization percentage 3. disk_read_block_size - Average read block size 4. disk_read_bps - Read bandwidth (bytes per second) 5. disk_read_iops - Read IOPS 6. disk_write_block_size - Average write block size 7. disk_write_bps - Write bandwidth (bytes per second) 8. disk_write_iops - Write IOPS

Time Aggregation Methods (--aggre-ops):

• SUM_OVER_TIME - Sum over time
• COUNT_OVER_TIME - Count over time
• AVG_OVER_TIME - Average over time
• MAX_OVER_TIME - Maximum over time
• MIN_OVER_TIME - Minimum over time
• SUM_OVER_TIME_LCRO - Sum over left-closed, right-open interval
• AVG_OVER_TIME_LCRO - Average over left-closed, right-open interval
• SUM_OVER_TIME_LORC - Sum over left-open, right-closed interval
• AVG_OVER_TIME_LORC - Average over left-open, right-closed interval

Cross-Disk Aggregation Methods (--aggre-over-line-ops):

• NON - No aggregation (default)
• SUM - Sum across disks
• AVG - Average across disks
• COUNT - Count across disks
• MAX - Maximum across disks
• MIN - Minimum across disks

Dimension Filters (--dimensions JSON fields):

• DiskId - Disk ID (e.g., ["d-bp1234567890"])
• DeviceType - Disk type (["system"] or ["data"])
• DeviceCategory - Disk category (e.g., ["cloud_essd"])
• EcsInstanceId - ECS instance ID (e.g., ["i-bp1234567890"])
• Azone - Availability zone (e.g., ["cn-hangzhou-a"])

Group By Labels (--group-by-labels):

• DiskId
• DeviceType
• DeviceCategory
• EcsInstanceId
• Azone

Period and Time Range Limits:

Example: Query single disk read IOPS:

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-bp1234567890\"]}" \
  --biz-region-id cn-hangzhou

Example: Query multiple disks with aggregation:

aliyun ebs describe-metric-data \
  --metric-name disk_write_bps \
  --start-time 2024-01-15T00:00:00Z \
  --end-time 2024-01-15T23:59:59Z \
  --period 300 \
  --dimensions "{\"DeviceType\": [\"data\"]}" \
  --aggre-ops AVG_OVER_TIME \
  --aggre-over-line-ops AVG \
  --biz-region-id cn-shanghai

Example: Group by disk category:

aliyun ebs describe-metric-data \
  --metric-name disk_iops_percent \
  --period 3600 \
  --aggre-ops MAX_OVER_TIME \
  --group-by-labels DeviceCategory \
  --biz-region-id cn-beijing

---

Configuration Commands

AI-Mode Configuration (Required for Skill Execution)

Credential Configuration

Plugin Management

---

Global Flags

These flags work with all aliyun ebs commands:

---

Complementary Commands (Not in This Skill)

These related EBS commands may be useful for extended analysis:

---

Command Validation

All commands in this document have been validated using:

aliyun ebs describe-metric-data --help

Verification Date: 2024-01-15 CLI Version: 3.3.2+

---

Reference

• Alibaba Cloud CLI Documentation
• EBS API Reference
• OpenAPI Explorer - DescribeMetricData

Verification Methods for EBS Disk Metric Analysis

This document provides detailed verification steps to ensure successful execution of EBS disk monitoring queries.

---

Overview

After querying disk metrics using aliyun ebs describe-metric-data, verify the results to ensure data accuracy and completeness.

---

Step 1: Verify API Response Structure

Check for Successful API Call

Every successful API response contains a RequestId field:

aliyun ebs describe-metric-data \
  --metric-name disk_read_iops \
  --biz-region-id cn-hangzhou \
  | jq '.RequestId'

Expected Output:

"11B55F58-D3A4-4A9B-9596-342420D0****"

If Missing: The API call failed. Check error messages in the response.

---

Step 2: Verify Data List Presence

Check DataList Array

aliyun ebs describe-metric-data \
  --metric-name disk_read_iops \
  --dimensions "{\"DiskId\": [\"d-bp1234567890\"]}" \
  --biz-region-id cn-hangzhou \
  | jq '.DataList | length'

Expected Output:

• 1 or more: Data found
• 0: No data (disk may not exist, no activity, or dimension filters exclude all disks)

Troubleshooting Empty DataList: 1. Verify disk exists in the region:

   aliyun ecs describe-disks --region cn-hangzhou --disk-ids '["d-bp1234567890"]'

2. Check if disk was active during the time range 3. Verify dimension filters are correct

---

Step 3: Verify Datapoints Content

Extract and Parse Datapoints

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-bp1234567890\"]}" \
  --biz-region-id cn-hangzhou \
  | jq '.DataList[0].Datapoints | fromjson'

Expected Output:

{
  "1705315200": 150,
  "1705315260": 148,
  "1705315320": 152,
  "1705315380": 145,
  ...
}

Verification Checks: 1. Timestamps: Unix timestamps should fall within the requested time range 2. Metric Values: Values should be reasonable for the metric type 3. Data Density: Number of datapoints should match (end_time - start_time) / period

Validate Timestamp Range

# Extract first and last timestamps
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-bp1234567890\"]}" \
  --biz-region-id cn-hangzhou \
  | jq '.DataList[0].Datapoints | fromjson | keys | [first, last]'

Expected: Timestamps near or within the query range.

---

Step 4: Verify Metric Value Ranges

Percentage Metrics (0-100%)

For metrics ending in _percent:

• disk_bps_percent
• disk_iops_percent

Validation:

aliyun ebs describe-metric-data \
  --metric-name disk_iops_percent \
  --dimensions "{\"DiskId\": [\"d-bp1234567890\"]}" \
  --biz-region-id cn-hangzhou \
  | jq '.DataList[0].Datapoints | fromjson | to_entries | map(select(.value < 0 or .value > 100))'

Expected Output: [] (empty array means all values are in valid range 0-100)

Throughput Metrics (Non-negative)

For BPS and IOPS metrics, values should be ≥ 0:

aliyun ebs describe-metric-data \
  --metric-name disk_read_bps \
  --dimensions "{\"DiskId\": [\"d-bp1234567890\"]}" \
  --biz-region-id cn-hangzhou \
  | jq '.DataList[0].Datapoints | fromjson | to_entries | map(select(.value < 0))'

Expected Output: [] (no negative values)

---

Step 5: Verify Aggregation Results

Time Aggregation Verification

When using --aggre-ops, verify aggregated values are within expected ranges:

# Query with AVG_OVER_TIME aggregation
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 \
  --aggre-ops AVG_OVER_TIME \
  --dimensions "{\"DiskId\": [\"d-bp1234567890\"]}" \
  --biz-region-id cn-hangzhou \
  | jq '.DataList[0].Datapoints | fromjson'

Check: Aggregated values should be within the range of raw values.

Cross-Disk Aggregation Verification

When using --aggre-over-line-ops, verify the result:

# Query multiple disks with AVG aggregation
aliyun ebs describe-metric-data \
  --metric-name disk_write_bps \
  --dimensions "{\"DeviceType\": [\"data\"]}" \
  --aggre-ops AVG_OVER_TIME \
  --aggre-over-line-ops AVG \
  --biz-region-id cn-hangzhou \
  | jq '.DataList | length'

Expected:

• 1 when aggregating across all disks (no grouping)
• N when grouping by a dimension (N = number of unique values in that dimension)

---

Step 6: Verify Group By Results

Check Grouping Labels

When using --group-by-labels, verify each group has correct labels:

aliyun ebs describe-metric-data \
  --metric-name disk_iops_percent \
  --period 300 \
  --group-by-labels DeviceCategory \
  --biz-region-id cn-hangzhou \
  | jq '.DataList[].Labels | fromjson'

Expected Output:

{"DeviceCategory": "cloud_essd"}
{"DeviceCategory": "cloud_ssd"}
{"DeviceCategory": "cloud_efficiency"}

Verification: Each Labels object should contain the grouped field(s).

---

Step 7: Check for Warnings

Review Warnings Array

aliyun ebs describe-metric-data \
  --metric-name disk_read_iops \
  --start-time 2024-01-15T00:00:00Z \
  --end-time 2024-01-15T23:59:59Z \
  --period 5 \
  --dimensions "{\"DiskId\": [\"d-bp1234567890\"]}" \
  --biz-region-id cn-hangzhou \
  | jq '.Warnings'

Common Warnings:

• "not complete." - Data may be incomplete for some time points
• Typically occurs when:
• Disk was inactive during part of the time range
• Data collection was interrupted
• Requested time range is very recent (data not yet fully aggregated)

Action:

• If warnings appear, verify data completeness by checking for gaps in timestamps
• Consider adjusting time range or accepting partial data

---

Step 8: Verify Total Count

Check TotalCount Field

aliyun ebs describe-metric-data \
  --metric-name disk_read_iops \
  --group-by-labels DiskId \
  --biz-region-id cn-hangzhou \
  | jq '.TotalCount'

Expected:

• Should match DataList array length
• Indicates total number of result series returned

Verification:

aliyun ebs describe-metric-data \
  --metric-name disk_read_iops \
  --group-by-labels DiskId \
  --biz-region-id cn-hangzhou \
  | jq '[.TotalCount, (.DataList | length)] | .[0] == .[1]'

Expected Output: true

---

Step 9: End-to-End Verification Script

Complete Verification Example

#!/bin/bash

METRIC_NAME="disk_read_iops"
DISK_ID="d-bp1234567890"
REGION="cn-hangzhou"
START_TIME="2024-01-15T10:00:00Z"
END_TIME="2024-01-15T11:00:00Z"
PERIOD=60

echo "=== Querying EBS Metric Data ==="
RESPONSE=$(aliyun ebs describe-metric-data \
  --metric-name "$METRIC_NAME" \
  --start-time "$START_TIME" \
  --end-time "$END_TIME" \
  --period "$PERIOD" \
  --dimensions "{\"DiskId\": [\"$DISK_ID\"]}" \
  --biz-region-id "$REGION")

echo "$RESPONSE" | jq .

echo ""
echo "=== Verification Results ==="

# Check 1: RequestId present
REQUEST_ID=$(echo "$RESPONSE" | jq -r '.RequestId')
if [ "$REQUEST_ID" != "null" ] && [ -n "$REQUEST_ID" ]; then
  echo "✅ RequestId present: $REQUEST_ID"
else
  echo "❌ RequestId missing - API call failed"
  exit 1
fi

# Check 2: DataList not empty
DATA_COUNT=$(echo "$RESPONSE" | jq '.DataList | length')
if [ "$DATA_COUNT" -gt 0 ]; then
  echo "✅ DataList contains $DATA_COUNT series"
else
  echo "⚠️  DataList is empty - no data found"
fi

# Check 3: Datapoints present
if [ "$DATA_COUNT" -gt 0 ]; then
  DATAPOINTS=$(echo "$RESPONSE" | jq -r '.DataList[0].Datapoints')
  POINT_COUNT=$(echo "$DATAPOINTS" | jq 'fromjson | length')
  echo "✅ Datapoints contains $POINT_COUNT time series values"
fi

# Check 4: Warnings
WARNINGS=$(echo "$RESPONSE" | jq -r '.Warnings // [] | length')
if [ "$WARNINGS" -eq 0 ]; then
  echo "✅ No warnings"
else
  echo "⚠️  $WARNINGS warning(s) present:"
  echo "$RESPONSE" | jq -r '.Warnings[]'
fi

# Check 5: TotalCount matches DataList
TOTAL_COUNT=$(echo "$RESPONSE" | jq '.TotalCount')
if [ "$TOTAL_COUNT" -eq "$DATA_COUNT" ]; then
  echo "✅ TotalCount ($TOTAL_COUNT) matches DataList length ($DATA_COUNT)"
else
  echo "⚠️  TotalCount ($TOTAL_COUNT) does not match DataList length ($DATA_COUNT)"
fi

echo ""
echo "=== Verification Complete ==="

Usage:

chmod +x verify-metric-query.sh
./verify-metric-query.sh

---

Common Issues and Verification

---

Reference

• EBS DescribeMetricData API Documentation
• JMESPath Tutorial
• jq Manual