# ecs-monitoring-api

Part of **ECS**

# ECS Monitoring

## Capabilities Overview

| Sub-capability | Calling Mode | Description |
|----------------|--------------|-------------|
| Query Disk Monitor Data | Synchronous | Retrieve second-level monitoring data for AutoPL cloud disks, including Burst IO counts, aggregated hourly. |
| Get EIP Monitor Data | Synchronous | Retrieve monitoring data for Elastic IP addresses (note: this API is deprecated; use alternative APIs). |

## API Calling Patterns

### Authentication
The primary authentication method is Bearer Token.

- Include the header: `Authorization: Bearer <your_api_key>`
- Store your API key in the environment variable: `DASHSCOPE_API_KEY`
- While other auth methods may exist in Alibaba Cloud, Bearer Token is used consistently across these monitoring endpoints.

### Service Endpoint
APIs use region-specific endpoints with the pattern:

`https://api.alibabacloud.com/api/{product}/{version}/{action}`

Common regions include:
- `cn-hangzhou`
- `cn-shanghai`
- `cn-beijing`

For disk monitoring, the product is `ebs`; for EIP monitoring, it is `Ecs`.

### Synchronous Pattern
Both functions use a synchronous request-response pattern:

1. Send a POST request to the endpoint with required parameters in the body (typically JSON or form-encoded).
2. Include the `Authorization: Bearer <token>` header.
3. Receive a complete JSON response immediately (no polling or streaming).
4. Handle pagination using `MaxResults` and `NextToken` if `TotalCount` exceeds page size.

## Parameter Reference

### Query Disk Monitor Data

| Parameter | Type | Required | Default | Constraints | Description |
|----------|------|----------|---------|-------------|-------------|
| RegionId | string | Yes | — | — | Region ID. Use `DescribeRegions` to get supported regions. |
| Type | string | Yes | — | one of: pro | Monitoring data type. Only `pro` (Burst IO) is supported. |
| DiskIds | string | No | — | — | Comma-separated list of disk IDs in JSON array format. |
| StartTime | string | Yes | — | ISO 8601 format: yyyy-MM-ddTHH:mm:ssZ | Start time in UTC+0. |
| EndTime | string | Yes | — | ISO 8601 format: yyyy-MM-ddTHH:mm:ssZ | End time in UTC+0. |
| MaxResults | string | No | 10 | range 1-100 | Max items per page. Enables pagination when set. |
| NextToken | string | No | — | — | Token from previous response for next page. |

### Get EIP Monitor Data
This API is deprecated and has no documented parameters in the current reference. Users should migrate to newer monitoring APIs.

## Code Examples

### Query Disk Monitor Data - Python - cn-hangzhou

```python
import requests
import os
import json

url = "https://api.alibabacloud.com/api/ebs/2021-07-30/DescribeDiskMonitorDataList"
headers = {
    "Authorization": f"Bearer {os.getenv('DASHSCOPE_API_KEY')}",
    "Content-Type": "application/json"
}
payload = {
    "RegionId": "cn-hangzhou",
    "Type": "pro",
    "StartTime": "2022-06-01T07:00:00Z",
    "EndTime": "2022-06-01T09:00:00Z",
    "MaxResults": "10"
}

response = requests.post(url, headers=headers, json=payload)
print(json.dumps(response.json(), indent=2))
```

### Get EIP Monitor Data (Deprecated) - Python - All Regions

```python
import requests
import os

url = "https://api.alibabacloud.com/api/Ecs/2014-05-26/DescribeNewProjectEipMonitorData"
headers = {
    "Authorization": f"Bearer {os.getenv('DASHSCOPE_API_KEY')}",
    "Content-Type": "application/json"
}

response = requests.post(url, headers=headers)
print(response.json())
```

### Query Disk Monitor Data with Pagination - Bash - International

```bash
#!/bin/bash
export DASHSCOPE_API_KEY="your_api_key_here"

curl -X POST \
  https://api.aliyun.com/api/ebs/2021-07-30/DescribeDiskMonitorDataList \
  -H "Authorization: Bearer $DASHSCOPE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "RegionId": "cn-shanghai",
    "Type": "pro",
    "StartTime": "2023-01-01T00:00:00Z",
    "EndTime": "2023-01-01T01:00:00Z",
    "MaxResults": "50"
  }'
```

### Basic Disk Query - Python - China

```python
import requests
import os

url = "https://api.aliyun.com/api/ebs/2021-07-30/DescribeDiskMonitorDataList"
headers = {"Authorization": f"Bearer {os.environ['DASHSCOPE_API_KEY']}"}
data = {
    "RegionId": "cn-beijing",
    "Type": "pro",
    "StartTime": "2023-10-01T12:00:00Z",
    "EndTime": "2023-10-01T13:00:00Z"
}

resp = requests.post(url, headers=headers, json=data)
print(resp.json())
```

## Response Format

```json
{
  "RequestId": "473469C7-AA6F-4DC5-B3DB-A3DC0DE3****",
  "MonitorData": [
    {
      "DiskId": "d-bp67acfmxazb4p****",
      "Timestamp": "2022-06-01T08:00:00Z",
      "BurstIOCount": 2000
    }
  ],
  "TotalCount": 3,
  "NextToken": "e71d8a535bd9c****"
}
```

**Key Fields**:
- `RequestId` — Unique ID for troubleshooting
- `MonitorData[].DiskId` — ID of the monitored disk
- `MonitorData[].Timestamp` — UTC timestamp of the data point
- `MonitorData[].BurstIOCount` — Number of Burst IO operations in the hour
- `TotalCount` — Total number of records matching the query
- `NextToken` — Token for fetching the next page of results

## Error Handling

| Error Code | Description | Recommended Action |
|------------|-------------|---------------------|
| 400 | InvalidParameter: Parameter error | Validate all parameters against constraints (e.g., ISO 8601 time format, valid RegionId) |
| 403 | Forbidden: Insufficient permissions | Check RAM policies; ensure your account has `ebs:DescribeDiskMonitorDataList` permission |
| 404 | NoSuchResource: Resource does not exist | Verify DiskId or EIP exists in the specified region |
| 500 | InternalError: Server processing failure | Retry the request; if persistent, contact support with RequestId |
| 504 | RequestTimeout: Request timed out | Reduce time range or number of resources; retry with exponential backoff |

## Pricing & Billing

### Billing Model
Per-request billing: each API call is charged as one request.

### Price Reference

| Tier | Input Price | Output Price |
|------|-------------|--------------|
| default | 0.001 / | 0.001 / |

### Free Tier
1000 free calls per month.

### Usage Limits
- Disk monitoring: max 100 records per request
- EIP monitoring: max 1000 records per request (deprecated API)

### Billing Notes
Charged per call after free tier is exhausted. Each invocation counts as one request regardless of result size.

## FAQ

Q: What monitoring data is available for cloud disks?
A: Currently, only Burst IO count data for AutoPL disks is supported, aggregated hourly. Standard cloud disks do not provide this metric.

Q: Why am I getting a 403 error when calling the disk monitoring API?
A: Your RAM user likely lacks the `ebs:DescribeDiskMonitorDataList` permission. Ask your administrator to attach a policy granting this action.

Q: Is the EIP monitoring API still usable?
A: The `DescribeNewProjectEipMonitorData` API is deprecated. While it may still function, Alibaba Cloud recommends migrating to newer CloudMonitor APIs for EIP metrics.

Q: How do I handle large result sets?
A: Use pagination: set `MaxResults` (1–100) and use the returned `NextToken` in subsequent requests until `NextToken` is absent.

Q: What time zone should I use for StartTime and EndTime?
A: Always use UTC+0 in ISO 8601 format (e.g., `2023-01-01T12:00:00Z`). Do not use local time zones.