(cloudwatch): GaugeWidget cannot handle nested annotations

[fokkobucys]

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:

"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:

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:

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.