# rds-events

Part of **RDS**

# ApsaraDB RDS Event Management

## Capabilities Overview

| Sub-capability | Calling Mode | Description |
|----------------|--------------|-------------|
| Manage Event History | Synchronous | Enable, disable, and query historical events for monitoring and auditing purposes. |

## API Calling Patterns

### Authentication
Use **Bearer Token** authentication via the `Authorization` header. This is the primary and recommended method for all RDS Event Management APIs.

- Header format: `Authorization: Bearer <your_api_key>`
- Environment variable: `ALIYUN_API_KEY` (or `DASHSCOPE_API_KEY` in some examples)
- Note: While Alibaba Cloud also supports AccessKey-based signature authentication for other services, the Event Management API examples consistently use Bearer token headers.

### Service Endpoint
All APIs use a single global endpoint:

- Base URL: `https://rds.aliyuncs.com/`
- Method: `GET` or `POST` depending on the operation
- Region: The `RegionId` parameter specifies the target region (e.g., `cn-hangzhou`, `cn-shanghai`, `cn-beijing`). The endpoint itself is not region-specific.

### Synchronous API Pattern
All Event Management operations follow a **Synchronous** pattern:
1. Send an HTTP request with required parameters (including `Action`, `RegionId`, and authentication)
2. Receive a JSON response immediately
3. Parse the response for success data or error codes
4. No polling or async handling is needed

Common actions include:
- `ModifyActionEventPolicy`: Enable/disable event history
- `DescribeActionEventPolicy`: Check if event history is enabled
- `DescribeEvents`: Retrieve paginated list of historical events

## Parameter Reference

### Manage Event History

| Parameter | Type | Required | Default | Constraints | Description |
|----------|------|----------|---------|-------------|-------------|
| Action | string | Yes | — | — | The operation to perform. Valid values: `ModifyActionEventPolicy`, `DescribeActionEventPolicy`, `DescribeEvents`. |
| RegionId | string | Yes | — | — | The ID of the region (e.g., `cn-hangzhou`). Use `DescribeRegions` to get valid IDs. |
| EnableEventLog | string | Yes (for ModifyActionEventPolicy) | — | one of: True, False | Specifies whether to enable event history logging. |
| StartTime | string | No | — | ISO 8601 UTC (yyyy-MM-ddTHH:mm:ssZ) | Start of time range for querying events. |
| EndTime | string | No | — | ISO 8601 UTC, must be > StartTime | End of time range for querying events. |
| PageSize | integer | No | 30 | one of: 30, 50, 100 | Number of events per page. |
| PageNumber | integer | No | 1 | positive integer | Page number to retrieve. |

## Code Examples

### Enable Event History - Bash - All Regions

```bash
curl -H 'Authorization: Bearer $ALIYUN_API_KEY' \
  'https://rds.aliyuncs.com/?Action=ModifyActionEventPolicy&RegionId=cn-hangzhou&EnableEventLog=True&<Common request parameters>'
```

### Query Event History Status - Python - All Regions

```python
from aliyunsdkcore.client import AcsClient
from aliyunsdkrds.request.v20140815 import DescribeActionEventPolicyRequest

client = AcsClient('<your-access-key-id>', '<your-access-key-secret>', 'cn-hangzhou')
request = DescribeActionEventPolicyRequest.DescribeActionEventPolicyRequest()
request.set_RegionId('cn-hangzhou')
response = client.do_action_with_exception(request)
print(response)
```

### Query Historical Events - Curl - All Regions

```bash
curl -H 'Authorization: Bearer $ALIYUN_API_KEY' \
  'https://rds.aliyuncs.com/?Action=DescribeEvents&RegionId=cn-hangzhou&StartTime=2019-08-20T01:30:00Z&EndTime=2019-08-20T01:35:00Z&<Common request parameters>'
```

### Disable Event History - Bash - All Regions

```bash
curl -H 'Authorization: Bearer $ALIYUN_API_KEY' \
  'https://rds.aliyuncs.com/?Action=ModifyActionEventPolicy&RegionId=cn-shanghai&EnableEventLog=False&<Common request parameters>'
```

## Response Format

```json
{
    "RequestId": "BAC0952C-0EB3-4DE7-A567-B83269BFE43F",
    "RegionId": "cn-hangzhou",
    "EnableEventLog": "True"
}
```

**Key Fields**:
- `RequestId` — Unique ID for the API request (useful for troubleshooting)
- `RegionId` — The region for which the policy applies
- `EnableEventLog` — Indicates whether event history is enabled (`True` or `False`)
- `EventItems[].EventName` — Name of the recorded event (e.g., `ModifySecurityIPList`)
- `EventItems[].EventTime` — Time the event occurred (UTC ISO 8601)
- `EventItems[].EventType` — Category of event (e.g., `SecurityManagement`)
- `EventItems[].ResourceName` — RDS instance ID associated with the event
- `TotalRecordCount` — Total number of matching events (for pagination)

## Error Handling

| Error Code (Code) | Description (Description) | Recommended Action (Recommended Action) |
|-------------------|----------------------------|----------------------------------------|
| AccessDenied | You do not have sufficient permissions to perform this operation. Check your RAM policy and ensure it includes the required permissions. | Verify your RAM user has `rds:DescribeActionEventPolicy` or `rds:ModifyActionEventPolicy` permissions. |
| InvalidRegionId.NotFound | The specified region ID does not exist. Verify the region ID and try again. | Use `DescribeRegions` API to get valid region IDs. |
| OperationNotSupported | The requested operation is not supported in the current region or for the specified instance type. Confirm the region and instance configuration. | Check regional availability of event history feature in RDS documentation. |
| Throttling | The request was throttled due to too many requests. | Reduce request frequency; implement exponential backoff. |

### Rate Limits & Retry
- **QPS Limit**: 100 queries per second per account (as noted in `DescribeActionEventPolicy`)
- **Retry Strategy**: Use exponential backoff (e.g., wait 1s, 2s, 4s...) on `Throttling` errors
- Respect the `Retry-After` header if provided (though not explicitly mentioned, standard practice applies)

## Requirements

- SDK: `aliyun-python-sdk-rds>=2.1.0` (for Python examples)
- Environment variable: `export ALIYUN_API_KEY=your_api_key_here`
- Common request parameters (such as `Version`, `Timestamp`, `Signature`) must be included as per Alibaba Cloud API standards

## FAQ

Q: How do I check if event history is enabled for my RDS instance?
A: Call the `DescribeActionEventPolicy` API with your `RegionId`. The response includes `EnableEventLog: "True"` or `"False"`.

Q: What types of events are recorded when event history is enabled?
A: Events include instance creation, parameter modifications, security group changes (e.g., `ModifySecurityIPList`), and other administrative actions performed by users or the system.

Q: Can I query events across multiple regions in one request?
A: No. Each API call is scoped to a single `RegionId`. You must make separate requests for each region.

Q: Are there any prerequisites to using these APIs?
A: Yes. You need an RDS instance in the target region and appropriate RAM permissions (`rds:DescribeEvents`, `rds:ModifyActionEventPolicy`, etc.).

Q: Why am I getting an "OperationNotSupported" error?
A: The event history feature may not be available in your region or for your RDS instance type. Verify regional support in the Alibaba Cloud RDS documentation.

## Pricing & Billing

### Billing Model
Per-request billing: each API call (successful or failed) counts as one request.

### Price Reference

| Tier | Input Price | Output Price |
|------|-------------|--------------|
| default | 0.001 / | 0.001 / |
| Standard | 0.0001 / | 0.0001 / |
| default | 0.002 / | 0.002 / |

### Free Tier
- 1000 free calls/month (for `ModifyActionEventPolicy`)
- 100 free requests/month (for `DescribeEvents`)
- 500 free requests/month for new accounts (for `DescribeActionEventPolicy`)

### Usage Limits
- Single request max size: 8192 characters
- QPS limit: 10 requests/second (for `ModifyActionEventPolicy`), 100 QPS (for others)
- Pagination: max 100 events per page

### Billing Notes
Each API invocation is billed regardless of success or failure. Event data retrieval does not incur additional charges beyond the per-request fee.