(cloudwatch): GaugeWidget cannot handle nested annotations
- Dominant language
- TypeScript
- Stars
- 12.9k
- Forks
- 4.6k
- Avg merge
- 2d 3h
- Merged PRs (30d)
- 83
Description
### Describe the bug
After the solution of #27720 for #25496, we can use annotations for GaugeWidgets. However, if we try to configure slightly more complex annotations, it seems not to be possible so far with CDK. In our use case, the target design of the GaugeWidget shall be like this:

This can be easily configured using the Management Console:

However, using the current allowed CDK code, constructs something like this:

### Expected Behavior
The mentioned manual deployment via Management Console generates the following configuration for the annotation:
```json
"annotations": {
"horizontal": [
{
"color": "#d62728",
"label": "Critical area",
"value": 80,
"fill": "above"
},
[
{
"color": "#f89256",
"label": "Heavy load area",
"value": 60
},
{
"value": 80,
"label": "Heavy load area"
}
],
{
"color": "#2ca02c",
"label": "Ok",
"value": 60,
"fill": "below"
}
]
}
```
Hence, I'd expect that this configuration is valid in the CDK code as well. So that this will be okay:
```typescript
const widget_ecs_cpu = new cw.GaugeWidget({
title: 'CPU',
width: 6,
height: 6,
leftYAxis: {
min: 0,
max: 100
},
legendPosition: cw.LegendPosition.HIDDEN,
metrics: [ecsMetrics_cpu],
liveData: true,
annotations: [
{
color: "#d62728",
label: 'Critical area',
value: 80,
fill: cw.Shading.ABOVE
},
[
{
color: "#f89256",
label: "Heavy load area",
value: 60
},
{
value: 80,
label: "Heavy load area"
}
],
{
color: "#2ca02c",
label: "OK",
value: 60,
fill: cw.Shading.BELOW
}
]
});
```
### Current Behavior
The actual problem is that the CDK does not support subordinated lists of annotations in the annotations list although this is accepted by CloudWatch itself. Trying this leads to the following syntax error:

Placing the annotations like this:
```typescript
const widget_ecs_docGeneration_cpu = new cw.GaugeWidget({
title: 'DocGen CPU',
width: 6,
height: 6,
leftYAxis: {
min: 0,
max: 100
},
legendPosition: cw.LegendPosition.HIDDEN,
metrics: [ecsMetrics_documentGeneration_cpu],
liveData: true,
annotations: [
{
color: "#d62728",
label: 'Critical area',
value: 80,
fill: cw.Shading.ABOVE
},
{
color: "#f89256",
label: "Heavy load area",
value: 60
},
{
color: "#f89256",
value: 80,
label: "Heavy load area"
},
{
color: "#2ca02c",
label: "OK",
value: 60,
fill: cw.Shading.BELOW
}
]
});
```
solves the syntax error but leads to the wrong display in the CloudWatch Dashboard as described above.
### Reproduction Steps
This can be reproduced by using the above provided code snippets. The GaugeWidget needs a metric and a Dashboard where it is included.
### Possible Solution
I think this might be quite straightforward as the allowed elements in the annotations array should not only be of type HorizontalAnnotation but also allow arrays of HorizontalAnnotations to reflect at least this special use case. At the moment I'm not aware of other formats of horizontal annotation allowed by CloudWatch.
### Additional Information/Context
_No response_
### CDK CLI Version
2.117.0
### Framework Version
2.117.0
### Node.js Version
v18.17.1
### OS
Windows 11
### Language
TypeScript
### Language Version
TypeScript 4.9.5
### Other information
We also tried raising the CDK library to the newest 2.127.0. This leads to the same behavior.
Contributor guide
Research direction
Start at the GaugeWidget annotations API and reproduce the issue with the supplied TypeScript snippets, using a metric and dashboard. Trace how nested horizontal annotations are represented in the generated dashboard configuration, then add coverage for the nested form and verify that the synthesized configuration matches the CloudWatch JSON shown in the issue.
Written by the indexing model from the issue text.
Assessment
- Tech stack
- aws, typescript
- Domain
- cloud, observability-sre
- Issue type
- Bug
- Difficulty
- 3/5
- Estimated time
- 1-2 days
- Activity status
- Stale
- Clarity
- Mostly clear
- Newbie friendliness
- 45/100