alibabacloud-ebs-disk-metric-analyzer

阿里云 EBS 云盘监控与指标分析

此技能可查询和分析阿里云弹性块存储（EBS）云盘的监控指标。它支持查询单个或多个云盘、执行时间序列聚合，以及进行跨云盘指标分析。

场景说明

监控和分析云盘性能指标，以便：

• 跟踪云盘 IOPS（每秒读写操作数）
• 监控云盘带宽（BPS，即每秒字节数）
• 分析云盘性能随时间的变化趋势
• 比较多个云盘的性能
• 按云盘类型、实例或可用区聚合指标
• 识别性能瓶颈和优化机会

架构：EBS 监控服务 + 云监控 + EBS 云盘（系统盘/数据盘）

支持的指标：

• disk_bps_percent - 云盘带宽利用率百分比
• disk_iops_percent - 云盘 IOPS 利用率百分比
• disk_read_block_size - 平均读取块大小
• disk_read_bps - 读取带宽（每秒字节数）
• disk_read_iops - 读取 IOPS
• disk_write_block_size - 平均写入块大小
• disk_write_bps - 写入带宽（每秒字节数）
• disk_write_iops - 写入 IOPS

聚合能力：

• 时间维度：对时间段执行 SUM、COUNT、AVG、MAX、MIN 聚合
• 跨云盘维度：按 SUM、AVG、COUNT、MAX、MIN 聚合多个云盘的指标
• 分组：按 DiskId、DeviceType、DeviceCategory、EcsInstanceId 或可用区分组

---

安装

预检查：需要 Aliyun CLI >= 3.3.3

运行 aliyun version 验证版本是否 >= 3.3.3。如果尚未安装或版本过低， 运行 curl -fsSL https://aliyuncli.alicdn.com/setup.sh | bash 进行安装/更新， 或参阅 references/cli-installation-guide.md 了解安装说明。

预检查：需要更新 Aliyun CLI 插件

[MUST] 运行 aliyun configure set --auto-plugin-install true 以启用自动安装插件。 [MUST] 运行 aliyun plugin update，确保所有现有插件始终为最新版本。

---

身份验证

预检查：需要阿里云凭证

安全规则：

• 绝不读取、回显或打印 AK/SK 值（例如，禁止使用 echo $ALIBABA_CLOUD_ACCESS_KEY_ID）
• 绝不要求用户在对话或命令行中直接输入 AK/SK
• 绝不使用 aliyun configure set 和明文凭证值
• 仅使用 aliyun configure list 检查凭证状态

aliyun configure list

检查输出中是否存在有效配置（AK、STS 或 OAuth 身份）。

如果不存在有效配置，请在此处停止。

1. 从阿里云控制台获取凭证
2. 在此会话之外配置凭证（在终端中使用 aliyun configure，或在 shell 配置文件中设置环境变量）
3. 返回并重新运行 aliyun configure list，确认显示有效配置

---

RAM 权限策略

此技能需要以下阿里云 RAM 权限。完整权限策略请参阅 references/ram-policies.md。

必需的 API 权限：

• ebs:DescribeMetricData - 查询云盘监控指标

**[MUST] 权限失败处理：**执行过程中任何时候，如果命令或 API 调用因权限错误而失败，请按以下流程处理：

1. 阅读 references/ram-policies.md，获取此 SKILL 所需的完整权限列表
2. 使用 ram-permission-diagnose 技能指导用户申请所需权限
3. 暂停操作，等待用户确认已授予所需权限

---

参数确认

重要：参数确认 — 执行任何命令或 API 调用之前， 必须与用户确认所有可由用户自定义的参数（例如 RegionId、DiskId、MetricName、时间范围、 聚合方法等）。未经用户明确批准，不得假定或使用默认值。

必需参数和可选参数

参数名称	必需/可选	描述	默认值
--metric-name	必需	要查询的指标（例如，disk_read_iops、disk_write_bps）	N/A
--biz-region-id	必需	地域 ID（例如，cn-hangzhou、cn-shanghai）	N/A
--start-time	可选	ISO 8601 格式的查询开始时间（yyyy-MM-ddTHH:mm:ssZ）	若开始时间和结束时间均为空，则为上一时间段
--end-time	可选	ISO 8601 格式的查询结束时间（yyyy-MM-ddTHH:mm:ssZ）	当前时间
--period	可选	数据粒度，单位为秒（5、10、60、300、600、3600）	5
--dimensions	可选	用于筛选 DiskId、DeviceType、DeviceCategory、EcsInstanceId、Azone 的 JSON	空（所有磁盘）
--aggre-ops	可选	时间聚合方法（AVG_OVER_TIME、SUM_OVER_TIME、MAX_OVER_TIME 等）	不聚合
--aggre-over-line-ops	可选	跨磁盘聚合（NON、SUM、AVG、COUNT、MAX、MIN）	NON
--group-by-labels	可选	按标签分组（DiskId、DeviceType、DeviceCategory、EcsInstanceId、Azone）	不分组

---

核心工作流

在核心工作流开始时（任何 CLI 调用之前）： [MUST] 启用 AI-Mode——执行 Agent Skill 时必须启用 AI-mode。 在任何 CLI 调用之前运行以下命令：

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

场景 1：查询单个磁盘指标

查询特定磁盘过去一小时的读取 IOPS：

# 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

预期输出：

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

场景 2：聚合查询多个磁盘

查询多个数据盘的平均写入带宽：

# 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

场景 3：按磁盘类别对指标分组

按磁盘类别（例如，cloud_essd）分组分析 IOPS 利用率：

# 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

场景 4：比较不同可用区的性能

比较不同可用区的磁盘性能：

# 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

场景 5：多维度筛选

查询连接到特定 ECS 实例的指定磁盘：

# 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] 在每个退出点都禁用 AI-Mode——无论出于何种原因，在提供最终响应之前，都必须先禁用 AI-mode。此要求适用于所有退出路径：工作流成功、工作流失败、错误/异常、用户取消、会话结束，或任何不再执行 CLI 命令的情况。 AI-mode 仅用于 Agent Skill 调用场景，技能停止运行后不得保持启用状态。

aliyun configure ai-mode disable

---

成功验证方法

查询指标后，请验证：

1. 响应状态：检查是否包含 RequestId（表示 API 调用成功）
2. 数据是否存在：确认 DataList 包含预期条目
3. 时间范围：确认 Datapoints 时间戳与请求的时间范围相符
4. 指标值：验证指标值是否处于预期范围内（例如，百分比为 0-100）
5. 无警告：检查 Warnings 数组是否为空，或查看其中的警告

详细验证步骤请参阅 references/verification-method.md。

---

清理

此技能仅查询监控数据，不会创建任何资源，因此无需清理。

---

最佳实践

1. 选择合适的周期：短期分析使用较短周期（5s、10s），长期趋势分析使用较长周期（300s、3600s）
2. 时间范围限制：遵守各周期对应的时间范围限制（例如，5s 周期最多支持 12 小时）
3. 合理使用筛选条件：应用 dimensions 筛选条件，以减少数据量并提升查询性能
4. 选择聚合方式：根据分析目标选择聚合方式（趋势分析使用 AVG，峰值检测使用 MAX，总量统计使用 SUM）
5. 按相关维度分组：按 DeviceCategory 分组以比较磁盘类型，按 Azone 分组以进行区域分析
6. 处理警告：如果存在 Warnings 数组，请检查其中的内容——它可能表示数据不完整
7. 注意时区：所有时间戳均使用 UTC+0（ISO 8601 格式）
8. 批量查询：查询多个磁盘时，在 dimensions 中使用数组筛选条件，而不是多次调用 API
9. 解析结果：以编程方式解析 JSON 的 Datapoints 字段，提取时间戳和值对
10. 监控配额：查询较长时间范围或多个磁盘时，请留意 API 速率限制

---

参考链接

参考文件	描述
references/ram-policies.md	EBS 监控 API 的完整 RAM 权限策略
references/related-commands.md	此技能中使用的所有 EBS CLI 命令
references/verification-method.md	详细的验证步骤和命令
references/acceptance-criteria.md	测试模式和验收标准
references/cli-installation-guide.md	Alibaba Cloud CLI 安装指南

---

常见问题与解决方案

问题：“InvalidParameter: The parameter MetricName is invalid”

• 解决方案：确认指标名称与 8 个受支持的指标之一完全一致（区分大小写）

问题：“InvalidParameter: Period exceeds time range limit”

• 解决方案：缩短时间范围或提高周期粒度（例如，较长时间范围使用 300s，而不是 5s）

问题：返回的 DataList 为空

• 解决方案：检查指定区域中是否存在磁盘，以及磁盘是否符合维度筛选条件

问题：数据不完整警告

• 解决方案：某些时间点可能没有可用指标；请调整时间范围，或检查该时段内的磁盘活动情况

---

高级用法

使用 JMESPath 查询

使用 --cli-query 筛选输出，以提取特定数据：

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

与其他工具结合使用

将结果传递给 jq 以进行高级 JSON 处理：

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}'

---

了解更多信息：

• Alibaba Cloud EBS 文档
• OpenAPI Explorer - DescribeMetricData