# Alibaba Cloud ECS CPU Inventory — CLI Reference

## Identity

```bash
aliyun sts GetCallerIdentity \
  --profile <profile> \
  --region <region> \
  --output json
```

Response field: `AccountId`.

---

## List ECS Instances

```bash
aliyun ecs DescribeInstances \
  --profile <profile> \
  --region <region> \
  --RegionId <region> \
  --pager \
  --output json
```

Key fields per `Instances.Instance[]`:

| API field | Output column |
|-----------|---------------|
| `InstanceId` | `instance_id` |
| `InstanceName` | `instance_name` |
| `CreationTime` | `created_time` (normalize to `YYYY-MM-DDTHH:MM:SS`) |
| `InstanceType` | `instance_type` |
| `Cpu` | `cpu_cores` |
| `Memory` | `memory_mb` |
| `Status` | `status` |

Pagination: `--pager` merges all pages automatically.

Filter by status (optional):

```bash
aliyun ecs DescribeInstances \
  --profile <profile> --region <region> \
  --RegionId <region> \
  --Status Running \
  --pager --output json
```

---

## CPU Metrics (Last 7 Days)

CloudMonitor API: `DescribeMetricList`

| Parameter | Value |
|-----------|-------|
| `Namespace` | `acs_ecs_dashboard` |
| `MetricName` | `CPUUtilization` |
| `Period` | `3600` (1 hour; 7 days ≈ 168 points) |
| `StartTime` | 7 days ago UTC, `YYYY-MM-DDTHH:MM:SSZ` |
| `EndTime` | now UTC, `YYYY-MM-DDTHH:MM:SSZ` |
| `Dimensions` | JSON array, max **50** instances per call |

Single instance:

```bash
START=$(date -u -v-7d +"%Y-%m-%dT%H:%M:%SZ")   # macOS
END=$(date -u +"%Y-%m-%dT%H:%M:%SZ")

aliyun cms DescribeMetricList \
  --profile <profile> \
  --region <region> \
  --Namespace acs_ecs_dashboard \
  --MetricName CPUUtilization \
  --Period 3600 \
  --StartTime "$START" \
  --EndTime "$END" \
  --Dimensions '[{"instanceId":"i-abc123"}]' \
  --Length 1440 \
  --output json
```

Batch (up to 50 IDs):

```bash
--Dimensions '[{"instanceId":"i-1"},{"instanceId":"i-2"}]'
```

`Datapoints` is a **JSON string**; parse with `jq`:

```bash
echo "$resp" | jq -r '.Datapoints' | jq .
```

Each point: `timestamp`, `instanceId`, `Average`, `Minimum`, `Maximum` (percent 0–100).

Paginate with `NextToken` until empty.

### Aggregation per instance

From all hourly datapoints for one `instanceId`:

- `cpu_avg_7d` = average of `Average`
- `cpu_max_7d` = max of `Maximum`
- `cpu_min_7d` = min of `Minimum`

Round to 1 decimal place for display.

---

## Time Helpers

**macOS:**

```bash
date -u -v-7d +"%Y-%m-%dT%H:%M:%SZ"
date -u +"%Y-%m-%dT%H:%M:%SZ"
```

**Linux:**

```bash
date -u -d '7 days ago' +"%Y-%m-%dT%H:%M:%SZ"
date -u +"%Y-%m-%dT%H:%M:%SZ"
```

---

## Common Errors

| Error | Action |
|-------|--------|
| CloudSSO access token is expired | `aliyun configure --profile <name>` |
| No `Datapoints` / empty array | Leave CPU columns blank; instance may be stopped or too new |
| `Forbidden.RAM` | Profile lacks `cms:DescribeMetricList` or `ecs:DescribeInstances` |
| Wrong region | CMS metrics are regional; `--region` must match instance region |

---

## International Site Notes

- Profiles configured via Cloud SSO / AK for **Alibaba Cloud International** use international endpoints automatically.
- Region IDs follow international naming (`ap-southeast-1`, `us-east-1`, `eu-central-1`, etc.).
- Do not use China-only endpoints (`*.aliyuncs.com` cn-hangzhou partition) unless the profile is explicitly China site.