alibabacloud-ebs-disk-metric-analyzer

What this skill does

# 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](https://ram.console.aliyun.com/manage/ak)
> 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 Name | Required/Optional | Description | Default Value |
|---------------|-------------------|-------------|---------------|
| `--metric-name` | **Required** | Metric to query (e.g., disk_read_iops, disk_write_bps) | N/A |
| `--biz-region-id` | **Required** | Region ID (e.g., cn-hangzhou, cn-shanghai) | N/A |
| `--start-time` | Optional | Query start time in ISO 8601 format (yyyy-MM-ddTHH:mm:ssZ) | Last period if both start/end empty |
| `--end-time` | Optional | Query end time in ISO 8601 format (yyyy-MM-ddTHH:mm:ssZ) | Current time |
| `--period` | Optional | Data granularity in seconds (5, 10, 60, 300, 600, 3600) | 5 |
| `--dimensions` | Optional | JSON filter for DiskId, DeviceType, DeviceCategory, EcsInstanceId, Azone | Empty (all disks) |
| `--aggre-ops` | Optional | Time aggregation method (AVG_OVER_TIME, SUM_OVER_TIME, MAX_OVER_TIME, etc.) | No aggregation |
| `--aggre-over-line-ops` | Optional | Cross-disk aggregation (NON, SUM, AVG, COUNT, MAX, MIN) | NON |
| `--group-by-labels` | Optional | Group 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 \
  --dime