feat(cloudwatch): render visible metrics first

[jackrein]

Issue #36079

Closes #36079.

Reason for this change

Multiple visible math expressions added to a graph are hard to distinguish, because the automatic CloudWatch color assignments assign contrasting colors to the invisible metrics. This change makes these types of graphs much easier to view.

Description of changes

Sorted metrics in rendering.ts ascending by level upon reading the property. Any top level metrics (i.e. math expressions) now appear before nested metrics. The visible metrics are now assigned contrasting colors.

Describe any new or updated permissions being added

No new permissions added

Description of how you validated changes

One unit test was added, dedicated for this behavior. I also synthesized this example project, and saw the metrics in the desired order.

Checklist

• My code adheres to the CONTRIBUTING GUIDE and DESIGN GUIDELINES

---

By submitting this pull request, I confirm that my contribution is made under the terms of the Apache-2.0 license

[aws-cdk-automation]

The pull request linter fails with the following errors:

❌ Features must contain a change to a README file.
❌ Features must contain a change to an integration test file and the resulting snapshot.

If you believe this pull request should receive an exemption, please comment and provide a justification. A comment requesting an exemption should contain the text Exemption Request. Additionally, if clarification is needed, add Clarification Request to a comment.

[jackrein]

In the CONTRIBUTING GUIDE for features, it states:

feat: indicates a feature added (requires tests and README updates in principle, but can be suppressed)

In my opinion, this feature is small enough that it probably doesn't warrant a README update or additional integration test. I could be convinced otherwise, though, and am happy to add those things if requested.

[pahud]

I saw this in your last CI error log

@aws-cdk-testing/framework-integ: Snapshot Results: 
@aws-cdk-testing/framework-integ: Tests:    1 failed, 1314 total
@aws-cdk-testing/framework-integ: Failed: /codebuild/output/src231279944/src/actions-runner/_work/aws-cdk/aws-cdk/packages/@aws-cdk-testing/framework-integ/test/aws-cloudwatch/test/integ.math-alarm-and-dashboard.js
@aws-cdk-testing/framework-integ: Error: Some tests failed!
@aws-cdk-testing/framework-integ: To re-run failed tests run: integ-runner --update-on-failed
@aws-cdk-testing/framework-integ:     at run (/codebuild/output/src231279944/src/actions-runner/_work/aws-cdk/aws-cdk/node_modules/@aws-cdk/integ-runner/lib/index.js:10650:13)
@aws-cdk-testing/framework-integ:     at async main (/codebuild/output/src231279944/src/actions-runner/_work/aws-cdk/aws-cdk/node_modules/@aws-cdk/integ-runner/lib/index.js:10556:5)
Notice: -testing/framework-integ: [Notice] You are using the new default engine to run integration tests. If you think the above failure has been caused by the new engine, you may choose to temporarily revert to the old engine by adding the `--unstable=deprecated-cli-engine` option. Please note that this engine is deprecated and scheduled to be removed in January 2026.
@aws-cdk-testing/framework-integ: If reverting to the old engine resolves an issue for you, please let us know so we can address this in the new engine. Report issues here: https://github.com/aws/aws-cdk-cli/issues/new/choose
@aws-cdk-testing/framework-integ: Error: integ-runner exited with error code 1
@aws-cdk-testing/framework-integ: Tests failed. Total time (3m28.4s) | integ-runner (2m15.5s) | /codebuild/output/src231279944/src/actions-runner/_work/aws-cdk/aws-cdk/node_modules/jest/bin/jest.js (1m10.2s)
@aws-cdk-testing/framework-integ: !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!

Looks like this integ is failing

framework-integ/test/aws-cloudwatch/test/integ.math-alarm-and-dashboard.js

you probably need to

cd framework-integ
yarn integ-runner test/aws-cloudwatch/test/integ.math-alarm-and-dashboard.js

and make sure it passes. If it failed you need

yarn integ-runner test/aws-cloudwatch/test/integ.math-alarm-and-dashboard.js --update-on-failed

to re-deploy and re-generate snapshots.

see https://github.com/aws/aws-cdk/blob/main/CONTRIBUTING.md#testing

[pahud]

If you need to modify any integ test, a useful trick is to have a separate terminal

cd framework-integ
yarn watch

This will incrementally compile when you update any .ts under that dir and re-generate .js
so you can yarn integ-runner against the updated .js for faster iteration.

see https://github.com/aws/aws-cdk/blob/main/CONTRIBUTING.md#yarn-watch-optional

Hope it helps!

[jackrein]

Thank you! I thought I had ran the integ tests locally, but I just built the framework. I was able to update the snapshots, but needed to use the --dry-run flag, since I don't have access to the integ test AWS account:

  FAILED     aws-cloudwatch/test/integ.math-alarm-and-dashboard-cdk-integ-math-alarm-and-dashboard/DefaultTest (default/us-east-1) 4.218s
      Integration test failed: AuthenticationError: Unable to resolve AWS account to use. It must be either configured when you define your CDK Stack, or through the environment

[pahud]

Hi @jackrein

--dry-run should be avoided as it doesn't guarantee a successful deployment and the generated snapshots can't be validated. As mentioned in the contributed guide

Please do not run the cdk-integ tool with --dry-run or manually update the snapshot.

To ensure the updated integ tests are deployable, you need a valid AWS account with CLI configured and yarn integ-runner will try to deploy the integ tests to your account and then immediately destroy the stacks, generating snapshots validated deployable. This ensures the updated integ tests can be deployed with no errors.

So let me clarify the process, you don't need the access to any AWS-owned integ test account, for integ testing, you just need to make sure you have your own AWS account configured with AWS CLI and yarn integ-runner will try deploy to your own AWS account. If it deploys, snapshots will be updated/generated and stacks in your account will immediately destroyed and you are ready to push the updated snapshots.

Let me know if it makes sense to you. Thank you.

[jackrein]

I was able to get the integ tests working in my personal AWS account – there are no changes to commit, so leaving the PR as is

% yarn integ test/aws-cloudwatch/test/integ.math-alarm-and-dashboard.js --update-on-failed
...
Running integration tests for failed tests...

Running in parallel across regions: us-east-1, us-east-2, us-west-2
Running test /Users/jack/dev/github/jackrein/aws-cdk/packages/@aws-cdk-testing/framework-integ/test/aws-cloudwatch/test/integ.math-alarm-and-dashboard.js in us-east-1
  SUCCESS    aws-cloudwatch/test/integ.math-alarm-and-dashboard-cdk-integ-math-alarm-and-dashboard/DefaultTest 124.013s

I was originally trying to use aws login, which didn't work (is this expected?). My ~/.aws/config looked like this:

[default]
login_session = arn:aws:iam::123456789012:user/user-name
region = us-east-1

Adding an Access Key and Secret Access Key to ~/.aws/credentials was what worked for me. I also needed to cdk bootstrap – I didn't see this in the integration test guide.