docs(cloudwatch): explain when period of each metric in usingMetrics for MathExpression is ignored

[go-to-k]

Issue # (if applicable)

Closes #.

Reason for this change

The usingMetrics property (Record<string, IMetric>) in MathExpressionProps has Metric objects with a period.

On the other hand, in the MathExpression construct, the period of each metric in the usingMetrics is ignored and instead overridden by the period of the MathExpression. Even if the period of the MathExpression is not specified, it is overridden by its default value.

https://github.com/aws/aws-cdk/blob/main/packages/aws-cdk-lib/aws-cloudwatch/lib/metric.ts#L606-L608

However the statement is not written in the JSDoc.

https://github.com/aws/aws-cdk/blob/main/packages/aws-cdk-lib/aws-cloudwatch/lib/metric.ts#L566

new MathExpression({
  expression: "m1+m2",
  label: "AlbErrors",
  usingMetrics: {
    m1: metrics.custom("HTTPCode_ELB_500_Count", {
      period: Duration.minutes(1), // <- ignored and overridden by default value `Duration.minutes(5)` of `period` in the `MathExpressionOptions`
      statistic: "Sum",
      label: "HTTPCode_ELB_500_Count",
    }),
    m2: metrics.custom("HTTPCode_ELB_502_Count", {
      period: Duration.minutes(1), // <- ignored and overridden by default value `Duration.minutes(5)` of `period` in the `MathExpressionOptions`
      statistic: "Sum",
      label: "HTTPCode_ELB_502_Count",
    }),
  },
}),

Description of changes

The current documentation could be confusing to users, so add this description.

Description of how you validated changes

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

[kaizencc]

In addition to this, what if we added a warning annotation anytime we find ourselves overwriting a different value? it's a little sinister to override a value and not tell the user when we do it.

[kaizencc]

haha i find this comment you've added to be confusing too :). Your PR description makes more sense than this, it might be helpful to even add an example or something here -- its not clear to me when and how i would know if my period is being overwritten.

[go-to-k]

I've rewritten it, what do you think?

b8b2ae0

[kaizencc]

the example is awesome! thanks so much

Pull request has been modified.

[go-to-k]

@kaizencc

Thanks for your review.

In addition to this, what if we added a warning annotation anytime we find ourselves overwriting a different value? it's a little sinister to override a value and not tell the user when we do it.

I added: 712e937

I have two questions:

1. Should I change the PR title from docs(cloudwatch): ... to something else? (I thought this PR was not docs because warning process added.) Or, should PRs be separated?

2. We can't warn only if the period in usingMetrics is set to the same value as the default value (Duration.minutes(5)), is there a problem?

It is correct usage to not specify a value for period (in usingMetrics), so we do not want to raise a warning in that case. However, if the period is not specified, it is overwritten with a default value, so we cannot determine whether the user has specified that value or if it has been overwritten. Therefore, warnings cannot be raised only in this case.

712e937#diff-289bad9fd897ab7808c177ad955a23faf18615ff8434f82b50fa0aeb54985de6R941

for example:

new MathExpression({
  expression:  'm1',
  label: 'AlbErrors',
  usingMetrics: {
    m1: metrics.custom('HTTPCode_ELB_500_Count', {
      period: Duration.minutes(5), // <- This is equal to the default value for `period`. So it is the same as not having specified.
      statistic: 'Sum',
      label: 'HTTPCode_ELB_500_Count',
    }),
  },
  period: Duration.minutes(3),
});

[aws-cdk-automation]

AWS CodeBuild CI Report

• CodeBuild project: AutoBuildv2Project1C6BFA3F-wQm2hXv2jqQv
• Commit ID: 56c657f
• Result: SUCCEEDED
• Build Logs (available for 30 days)

Powered by github-codebuild-logs, available on the AWS Serverless Application Repository

[go-to-k]

Hi, @kaizencc

Have you had a chance to look at the comment?

#30986 (comment)

[go-to-k]

@kaizencc

Could you please take a look at the comment? Do you have any good ideas to share?