aws / aws/aws-cdk

(rds): add CloudWatch metric helpers to DatabaseInstance

Open
#37,930 1 comment 0 reactions 0 assignees View on GitHub
@aws-cdk/aws-rds effort/medium feature-request p2
Dominant language
TypeScript
Stars
12.9k
Forks
4.6k
Avg merge
2d 3h
Merged PRs (30d)
83

Description

### Describe the feature

`DatabaseInstance` currently exposes only two CloudWatch metric helper methods
(`metricReadIOPS`, `metricWriteIOPS`), while AWS publishes many more
instance-level metrics in the `AWS/RDS` namespace.

Add helper methods on `DatabaseInstance` (and the `IDatabaseInstance` interface) for the commonly-used instance-level metrics, mirroring the pattern already established for `DatabaseCluster` (which has `metricServerlessDatabaseCapacity`,`metricACUUtilization`,`metricVolumeReadIOPs`,`metricVolumeWriteIOPs`).

Add helper methods on `DatabaseInstance` (and the `IDatabaseInstance`
interface) for the commonly-used instance-level metrics, mirroring the pattern
already established for `DatabaseCluster` (which has
`metricServerlessDatabaseCapacity`, `metricACUUtilization`,
`metricVolumeReadIOPs`, `metricVolumeWriteIOPs`).

Proposed additions:

- `metricCPUUtilization(props?)` → `CPUUtilization`
- `metricDatabaseConnections(props?)` → `DatabaseConnections`
- `metricFreeStorageSpace(props?)` → `FreeStorageSpace`
- `metricFreeableMemory(props?)` → `FreeableMemory`
- `metricNetworkReceiveThroughput(props?)` → `NetworkReceiveThroughput`
- `metricNetworkTransmitThroughput(props?)` → `NetworkTransmitThroughput`
- `metricReadLatency(props?)` → `ReadLatency`
- `metricWriteLatency(props?)` → `WriteLatency`
- `metricReadThroughput(props?)` → `ReadThroughput`
- `metricWriteThroughput(props?)` → `WriteThroughput`
- `metricSwapUsage(props?)` → `SwapUsage`
- `metricDiskQueueDepth(props?)` → `DiskQueueDepth`
- `metricBurstBalance(props?)` → `BurstBalance`
- `metricReplicaLag(props?)` → `ReplicaLag`

All listed metrics are documented as `Applies to: All` (or the relevant
engines) in the [Amazon CloudWatch metrics for Amazon RDS](https://docs.aws.am
azon.com/AmazonRDS/latest/UserGuide/rds-metrics.html#rds-cw-metrics-instance)
reference.

### Use Case

To alarm on common operational metrics like CPU utilization, free
storage, or DB connections for an RDS instance, users must hand-construct a
`cloudwatch.Metric` and remember the exact metric name and dimension key
(`DBInstanceIdentifier`):

```ts
new cloudwatch.Metric({
namespace: 'AWS/RDS',
metricName: 'CPUUtilization',
dimensionsMap: { DBInstanceIdentifier: instance.instanceIdentifier },
statistic: 'Average',
}).createAlarm(...);
```

With typed helpers, this becomes:

```ts
instance.metricCPUUtilization().createAlarm(...);
```

This:

- Matches `DatabaseCluster`'s ergonomics (no asymmetry between cluster and
instance APIs).
- Removes the foot-gun of misspelling metric names or forgetting dimensions.
- Enables IDE auto-completion for the canonical metric set.

PR #35773 already added `metricReadIOPS` / `metricWriteIOPS` in the same vein,
establishing both the pattern and that incremental additions are welcome.

Proposed Solution:
In `packages/aws-cdk-lib/aws-rds/lib/instance.ts`, after the existing
`metricReadIOPS` / `metricWriteIOPS` (lines ~344-355), add helper methods
following the same pattern. Example:

```ts
/**
* The percentage of CPU utilization.
*
* Average over 5 minutes
*/
public metricCPUUtilization(props?: cloudwatch.MetricOptions) {
return this.metric('CPUUtilization', { statistic: 'Average', ...props });
}

/**
* The number of database connections in use.
*
* Average over 5 minutes
*/
public metricDatabaseConnections(props?: cloudwatch.MetricOptions) {
return this.metric('DatabaseConnections', { statistic: 'Average', ...props
});
}
// ...
```

Mirror the corresponding declarations on the `IDatabaseInstance` interface so
they're available on imported instances.

### Proposed Solution

_No response_

### Other Information

Related precedent: PR #35773 (merged) added `metricReadIOPS` / `metricWriteIOPS` to `DatabaseInstance` and `metricVolumeReadIOPs` / `metricVolumeWriteIOPs` to `DatabaseCluster`. This issue extends the same pattern to the rest of the canonical instance-level metric set.

### Acknowledgements

- [x] I may be able to implement this feature request
- [ ] This feature might incur a breaking change

### AWS CDK Library version (aws-cdk-lib)

2.x.x

### AWS CDK CLI version

2.x.x

### Environment details (OS name and version, etc.)

MacOS Tahoe 26.5

Contributor guide

Open the contributing guide

Research direction

Start in packages/aws-cdk-lib/aws-rds/lib/instance.ts by reading the existing metricReadIOPS and metricWriteIOPS methods, then compare the corresponding DatabaseCluster helpers. Add the proposed metric helpers and matching declarations to IDatabaseInstance, preserving the established metric pattern and DBInstanceIdentifier dimension so imported instances expose the same API.

Written by the indexing model from the issue text.

Assessment

Tech stack
aws, typescript
Domain
cloud, databases
Issue type
Feature
Difficulty
3/5
Estimated time
1-2 days
Activity status
Quiet
Clarity
Clearly specified
Newbie friendliness
74/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.