(rds): add CloudWatch metric helpers to DatabaseInstance
- 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
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