--- name: alibabacloud-ebs-usage-summary description: | Analyze Alibaba Cloud block storage (EBS) disk performance and fleet composition. Use it to locate performance bottlenecks (saturated IOPS or bandwidth), compare disks, instances, or availability zones to decide where to tune or resize, review disk count and capacity by category / region / billing type to inform capacity and cost decisions, check disk event history, and reach the right console dashboard for deeper drill-down. Triggers: "EBS monitoring", "disk metrics", "cloud disk performance", "IOPS analysis", "BPS analysis", "disk monitoring data", "export disk monitoring data", "export monitoring data", "metric aggregation", "resource overview", "EBS Lens", "CloudLens for EBS", "disk usage report", "capacity distribution", "event overview", "monitoring dashboard", "EBS dashboard", "storage dashboard", "disk monitoring dashboard", "storage health", "block storage insights", "disk observability", "disk inventory summary", "telemetry console", "block storage analytics". --- # Alibaba Cloud EBS Disk Monitoring, Metric Analysis and Resource Overview This skill enables you to: 1. **Answer disk performance questions** — how busy a disk is, whether it is hitting its IOPS/bandwidth ceiling, how it trends over time, and how it compares with other disks, instances, or availability zones (via `aliyun ebs describe-metric-data`). 2. **Answer fleet composition questions** — how many disks and how much capacity the account holds, how that splits across disk categories, regions, and billing types (both absolute and as percentages), and what disk events occurred (via `aliyun ebs get-report` / `aliyun ebs list-reports`, the same data set behind the EBS Lens Resource Overview console page). 3. **Point users at the right dashboard** — console URLs for CloudMonitor and CloudLens for EBS, optionally with a quick text summary so the user knows what to look at before clicking through. ## Scenario Description ### A. Disk Performance Metrics Monitor and analyze cloud disk performance to track read/write IOPS and bandwidth (BPS), see how they trend over time, compare disks against each other, aggregate by disk type / instance / availability zone, and pinpoint bottlenecks and tuning opportunities. ### B. Resource Overview Reports (CloudLens for EBS) Retrieve aggregated resource reports covering: overall disk usage, disk count and capacity broken down by category (`cloud_essd`, `cloud_essd_entry`, `cloud_auto`, `local_ssd_pro`…), by region, and by billing (pay) type — each available as absolute values and as percentage shares — plus a disk event summary with event counts by event name and by region. > **[MUST] Scope limit — do not over-promise.** The 14 report cards this API returns are listed in [references/related-commands.md · Report Card Titles](references/related-commands.md). Encryption coverage, ESSD AutoPL adoption/burst usage, async replication pair count, dedicated block storage cluster count, and over-provisioned-disk detection are **not** among them. If the user asks for those, say the resource overview report does not expose them and point to the ECS console instead of inventing a figure. ### C. Monitoring Dashboard Quick View Point the user at the right console dashboard — **CloudMonitor** for real-time metrics and alarm rules, **CloudLens for EBS** for resource overview, disk health analysis, and optimization recommendations — optionally with a quick text summary of the latest report, then guide them into the deeper scenarios (1–8). **Architecture**: EBS Monitoring Service + Cloud Monitor + CloudLens for EBS + EBS Disks (System/Data Disks) > **[MUST · PRODUCT CONSTRAINT] All metric data MUST be queried through `aliyun ebs describe-metric-data`.** > > - **FORBIDDEN**: `aliyun cms ...` (CloudMonitor, e.g. `DescribeMetricList`), `aliyun ecs ...`, or any other product as a substitute for retrieving disk metric values. They expose different metric names and dimensions and do **not** satisfy this skill's contract. > - Resource overview data MUST come from the `ebs` product commands (`aliyun ebs get-report` / `aliyun ebs list-reports`) — never from CloudMonitor. > - `aliyun ecs describe-disks` is permitted for **one purpose only**: resolving a disk reference to a disk ID — either filtering by a given disk name, or listing a region's disks when the user supplied no identifier (see the Pre-Step under Scenario 5). It must never be used to fetch metric values. > - The CloudMonitor references in this document (including Scenario 9) denote **console navigation URLs for humans only** — they are *not* an API path. Providing a CloudMonitor console link is expected; calling a `cms` API is a workflow failure. **Supported Metrics**: `disk_read_iops` / `disk_write_iops` (read/write IOPS), `disk_read_bps` / `disk_write_bps` (read/write bandwidth in bytes per second), `disk_iops_percent` / `disk_bps_percent` (IOPS and bandwidth utilization percentage — the two to use for saturation questions), `disk_read_block_size` / `disk_write_block_size` (average block size). **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 **Supported Reports** (Resource Overview): Each report card is a `Datas[]` element identified by `Title` (e.g. `disk_count_percent_by_category`) and wrapping a nested `Data[]` array; every `Data[]` entry is one series with `Labels` (a JSON **object**, e.g. `{"category": "cloud_essd"}`) and `DataPoints` (a `{unix_seconds: value}` map at daily granularity). The 14 available cards cover overall usage, plus disk count and capacity by category / region / pay type (absolute and percentage), plus event summary and event counts. Enumerate the account's real titles with `--cli-query "Datas[].Title"` rather than hard-coding card names — see [references/related-commands.md](references/related-commands.md) for the full title list, verified payload shape, and parsing recipes. --- ## Installation **Pre-check: Aliyun CLI >= 3.3.3 required** > Run `aliyun version` to verify >= 3.3.3. If it is missing or too old, prefer a package manager (`brew install aliyun-cli`); otherwise follow `references/cli-installation-guide.md`, which installs into a user-writable directory. > > **[MUST] Installation safety:** never stream a remote script directly into a shell interpreter (that leaves no opportunity to inspect what will run) — download it, let the user review it, then run the local copy. Installing changes the user's machine, so **ask for confirmation first**, and never run privilege-elevating commands on the user's behalf. **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. --- ## Prerequisites > **[MUST] CloudLens for EBS must be enabled before using the Resource Overview feature.** > > 1. Log in to the [ECS Console](https://ecs.console.aliyun.com/) and open **Data Insights (EBS Lens) > Resource Overview** from the left-hand navigation. > 2. If CloudLens for EBS has not been enabled, click the **Enable Now** button on that page. > 3. After enabling, resource overview data takes approximately **10 minutes** to prepare. During this period, `get-report` will return an empty `Datas` array — this is NOT an error. > 4. The region passed to the resource overview commands MUST be a region where CloudLens for EBS is enabled. > > Reference: [Introduction to Block Storage Data Insights](https://help.aliyun.com/zh/ecs/user-guide/what-is-a-piece-of-data-is-stored-insight/) --- ## Authentication This skill relies on the Alibaba Cloud default credential chain. No explicit credential configuration is required within the skill session. > **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** (POP action identifiers — the CLI itself is always invoked in plugin mode). All four are **read-only query actions**: - `ebs:DescribeMetricData` — query disk monitoring metrics (`aliyun ebs describe-metric-data`) - `ebs:GetReport` — retrieve a CloudLens for EBS resource overview report (`aliyun ebs get-report`) - `ebs:ListReports` — list historical CloudLens for EBS resource overview reports (`aliyun ebs list-reports`) - `ecs:DescribeDisks` — resolve a disk name to a disk ID, or list a region's disks when no identifier was given (`aliyun ecs describe-disks`; see the Scenario 5 Pre-Step — never used to fetch metric values) > **[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 > **[MUST · MANDATORY GATE] Before executing any `aliyun ebs ...` command, output a parameter checklist** listing every user-customizable parameter you are about to use — including documented defaults, which must never be applied silently. Skipping the checklist is a workflow failure. > > Then choose one of two branches: > > - **Branch A — Interactive Confirmation** (default): ask the user to confirm or modify the checklist and **WAIT for an explicit reply** before any CLI command. Required when a parameter is missing/ambiguous, when the query is wide-scope (> 30 days or a whole region unfiltered), or when re-entering after a failure. > - **Branch B — Unattended Auto-Proceed**: print the checklist as a notification and proceed without waiting. Allowed only when the input is fully specified, the user explicitly asked for auto-run, or no follow-up reply is possible (automated evaluation / CI). > > When branches conflict, **Branch A wins**. > > **[MUST] Ambiguity clarification is never skippable.** If a required parameter is missing or ambiguous, you MUST ask an explicit, separate, user-facing question that names each missing parameter, states the value you would assume and why, and invites correction — even in unattended runs (there, ask, then proceed on the stated assumptions and repeat the open questions in the final answer). Jumping straight to "parameters auto-locked" when a required parameter was never supplied is FORBIDDEN. > > **Full rule set — branch triggers B1-B3 / A1-A3, conflict carve-outs, and clarification phrasing: [references/parameter-confirmation.md](references/parameter-confirmation.md). Read it whenever the branch choice is not obvious.** ### Required and Optional Parameters > **[MUST · plugin mode]** Every `aliyun ebs` command runs in **plugin mode**: lowercase-hyphenated command name and lowercase-hyphenated flags. Never use a PascalCase action name or PascalCase flags — the only PascalCase values that remain are **JSON payload keys** inside `--dimensions` (e.g. `DiskId`) and the POP action identifiers in `related_apis.yaml` / RAM policies. > > **The region flag is `--biz-region-id`, not `--region-id`** — the bare `--region` is a reserved CLI global flag for endpoint overrides. Treat `aliyun ebs --help` as the authority over this document; if a command is rejected as unknown, the local plugin is stale — run `aliyun plugin update` and retry the same form. | Command | Required | Key optional flags | |---------|----------|--------------------| | `describe-metric-data` | `--metric-name`, `--biz-region-id` | `--start-time` / `--end-time` (ISO 8601 UTC), `--period` (5/10/60/300/600/3600, default 5), `--dimensions` (JSON filter), `--aggre-ops` (`*_OVER_TIME`), `--aggre-over-line-ops` (`NON`/`SUM`/`AVG`/`COUNT`/`MAX`/`MIN`), `--group-by-labels` | | `get-report` | `--biz-region-id` | `--report-type` (`present` default / `history`), `--app-name` (default `default`), `--report-id` (**required** when type is `history`) | | `list-reports` | `--biz-region-id` (pass explicitly) | `--page-size` (10) / `--page-number` (1), `--app-id`, `--max-results` / `--next-token` | Full parameter semantics, valid values, time-range limits per period, and response formats: [references/related-commands.md](references/related-commands.md). --- ## 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, and use it wherever `` appears below. **Rule: every `aliyun` CLI command that calls a cloud API MUST include this flag** (local utility commands — `configure`, `plugin`, `version` — do not support it and are excluded): ``` --user-agent AlibabaCloud-Agent-Skills/alibabacloud-ebs-usage-summary/ ``` Do not skip, alter the format, or omit it on any API invocation. The flag is accepted by the `ebs` plugin commands even though `--help` does not list it among the global flags (verified with `--cli-dry-run` on CLI 3.4.7). Use `--cli-dry-run` to inspect any command's assembled request without calling the API. --- ## Core Workflow > **[MUST · ENTRY GATE]** The first step of every scenario below is the Parameter Confirmation gate: output the checklist, then either wait for confirmation (Branch A) or proceed with it as a notification (Branch B). The `# Confirm with user: ...` comment inside each Scenario is only a *reminder* of this gate — the gate itself is the explicit checklist output. > > **[MUST · RE-ENTRY GATE]** Any **2 consecutive** command failures (timeout, non-zero exit, gateway 5xx) MUST trigger the **Hard Stop** procedure in `references/error-handling.md §1` and re-enter the gate on Branch A — a 3rd silent retry without a user-facing Hard Stop message is a workflow failure. ### Placeholders in the Scenario Templates > **[MUST] The commands below are templates, not literal commands.** Every `<...>` token is a value you derive per run — never send a placeholder, or a value copied from this document, to the API. > > - `` — from the user's request; if absent, the CLI default profile region, which must be named in the clarification question > - `` / `` — from the user's request, or resolved via the Scenario 5 Pre-Step (`describe-disks` returns both `DiskId` and `InstanceId`) > - `` / `` — ISO 8601 UTC (`yyyy-MM-ddTHH:mm:ssZ`); compute relative windows ("last hour") from the current UTC time > - `` — the smallest granularity whose time-range limit covers the window > - `` — `HistoryReports[].ReportId` from a `list-reports` response (Scenario 7) > - `` — the session ID generated in `## Observability` > > The metric name, aggregation, and grouping in each template are likewise examples — substitute what the user actually asked for. Full placeholder table and per-period time-range limits: [references/related-commands.md](references/related-commands.md). ### Scenario 1: Query Single Disk Metrics Query a per-disk metric (here read IOPS) for one disk over a bounded window: ```bash # Confirm with user: region, disk ID, metric name, time range aliyun ebs describe-metric-data \ --metric-name disk_read_iops \ --start-time \ --end-time \ --period \ --dimensions "{\"DiskId\": [\"\"]}" \ --biz-region-id \ --user-agent AlibabaCloud-Agent-Skills/alibabacloud-ebs-usage-summary/ ``` **Expected Output**: `TotalCount`, plus one `DataList[]` entry per matched series carrying `Labels` (the dimension values) and `Datapoints` (a JSON string mapping Unix seconds to metric values), and a `RequestId`. See [references/related-commands.md · Response Format](references/related-commands.md) for a full sample payload. ### Scenario 2: Query Multiple Disks with Aggregation Aggregate a metric across a set of disks selected by dimension (here average write bandwidth over all data disks): ```bash # Confirm with user: region, metric name, device type, aggregation method aliyun ebs describe-metric-data \ --metric-name disk_write_bps \ --start-time \ --end-time \ --period \ --dimensions "{\"DeviceType\": [\"data\"]}" \ --aggre-ops AVG_OVER_TIME \ --aggre-over-line-ops AVG \ --biz-region-id \ --user-agent AlibabaCloud-Agent-Skills/alibabacloud-ebs-usage-summary/ ``` > Swap `DeviceType` for any other dimension the user scoped the question to (`DiskId`, `DeviceCategory`, `EcsInstanceId`, `Azone`), and choose `--aggre-over-line-ops` to match the question: `AVG` for typical load, `MAX` for worst case, `SUM` for total throughput. ### Scenario 3: Group Metrics by Disk Category Break a metric down by one label instead of collapsing it (here peak IOPS utilization per disk category): ```bash # Confirm with user: region, metric name, grouping dimension aliyun ebs describe-metric-data \ --metric-name disk_iops_percent \ --start-time \ --end-time \ --period \ --aggre-ops MAX_OVER_TIME \ --group-by-labels DeviceCategory \ --biz-region-id \ --user-agent AlibabaCloud-Agent-Skills/alibabacloud-ebs-usage-summary/ ``` ### Scenario 4: Compare Performance Across Availability Zones Same grouping mechanism applied to `Azone` to compare zones: ```bash # Confirm with user: region, metric name, grouping by Azone aliyun ebs describe-metric-data \ --metric-name disk_bps_percent \ --start-time \ --end-time \ --period \ --aggre-ops AVG_OVER_TIME \ --aggre-over-line-ops AVG \ --group-by-labels Azone \ --biz-region-id \ --user-agent AlibabaCloud-Agent-Skills/alibabacloud-ebs-usage-summary/ ``` ### Scenario 5: Multi-Dimension Filtering Combine dimensions when the user scopes the question to specific disks **and** specific instances. Dimension values are AND-ed across keys and OR-ed within a key's array: ```bash # Confirm with user: region, disk IDs, instance ID aliyun ebs describe-metric-data \ --metric-name disk_read_bps \ --start-time \ --end-time \ --period \ --dimensions "{\"DiskId\": [\"\", \"\"], \"EcsInstanceId\": [\"\"]}" \ --aggre-ops AVG_OVER_TIME \ --biz-region-id \ --user-agent AlibabaCloud-Agent-Skills/alibabacloud-ebs-usage-summary/ ``` #### Pre-Step: Resolving a Disk Name to a Disk ID `describe-metric-data` only accepts **disk IDs** in `--dimensions`, never disk names. When the user supplies a disk *name*, resolve it first via ECS: ```bash # ECS disk queries also run in plugin mode — flags are lowercase-hyphenated aliy