RFC: Log Alarm L2 Construct by rodrigotuna · Pull Request #962 · aws/aws-cdk-rfcs

rodrigotuna · 2026-07-03T14:32:52Z

Tracking issue: #960

This RFC proposes a new LogAlarm L2 construct in aws-cdk-lib/aws-cloudwatch, wrapping the AWS::CloudWatch::LogAlarm CloudFormation resource. It follows the accepted PromQLAlarm precedent (extends AlarmBase, reuses existing enums, interchangeable via IAlarm).

A proof-of-concept construct with unit tests and an integration test has been implemented and deployed against a real account, confirming it creates a valid AWS::CloudWatch::LogAlarm.

See text/0960-logalarm-l2.md.

chintan-vaghani2008 · 2026-07-07T09:59:34Z

+a scheduled Logs query (a query string + aggregation over one or more log groups) and compares the aggregated result
+against a threshold using an M-out-of-N evaluation. It also can surface matching log lines in the alarm notification.
+The construct wraps the `AWS::CloudWatch::LogAlarm` CloudFormation resource, reuses the existing
+`ComparisonOperator`/`TreatMissingData` enums, and — like `Alarm` and `PromQLAlarm` — extends `AlarmBase` so it is


Please note that ComparisonOperator we use for log alarm doesn't support LessThanLowerOrGreaterThanUpperThreshold | LessThanLowerThreshold | GreaterThanUpperThreshold being supported under Metric Alarm. These operations are supported for anomaly detection metric alarm and it is not supported for log alarm.

We can still use this enum and validate the parameter at synth. ( Probably, PromQL should also be doing the similar thing if they are reusing the enum ?)

I see you already covered below:

comparisonOperator must be a static-threshold operator (anomaly-detection operators rejected).

chintan-vaghani2008 · 2026-07-07T10:12:43Z

+## Summary
+
+`LogAlarm` lets customers alarm directly on logs. Instead of a metric + threshold + evaluation periods, a log alarm runs
+a scheduled Logs query (a query string + aggregation over one or more log groups) and compares the aggregated result


nit: Logs insight query

chintan-vaghani2008 · 2026-07-07T10:20:25Z

+    logGroupIdentifiers: [logGroup.logGroupName],
+    scheduledQueryRole: queryRole,
+    schedule: {
+      frequency: Duration.minutes(5),


nit: Should we just name it as rate to align it with scheduled expression rate expression naming ?

chintan-vaghani2008 · 2026-07-07T10:21:50Z

+import { Duration } from 'aws-cdk-lib';
+
+declare const logGroup: logs.LogGroup;
+declare const queryRole: iam.IRole;


Can we see if SQ ( as in GA) supports anything to help the role creation ? If so, customers can use that to simplify the role creationrather than having their own code to create one.

If there is one, we can also replicate the similar thing for log line role as well.

chintan-vaghani2008 · 2026-07-07T10:25:02Z

+declare const logAlarm: cloudwatch.LogAlarm;
+declare const topic: sns.Topic;
+
+logAlarm.addAlarmAction(new cloudwatch_actions.SnsAction(topic));


Let's see if we can add validation on supported actions for log alarm as well on synth ?

chintan-vaghani2008 · 2026-07-07T10:32:27Z

+### Are there any open issues that need to be addressed later?
+
+- Alignment of `ScheduledQueryConfiguration` field constraints across the Coral model, CFN schema, and Hermes validation
+  (tracked in EVENTS-4979): `LogGroupIdentifiers` required→optional, `StartTimeOffset` range `[1, 2592000]`,


Can't we just publish this with updated schema given we have already started the deployments? Or we plan to update it once we complete all deployments?

Also, curious if these validations will be done at L1 construct based on CFN schema being published ?

chintan-vaghani2008 · 2026-07-07T10:36:52Z

+  readonly treatMissingData?: TreatMissingData;          // @default - service default
+  readonly actionLogLineCount?: number;                  // 0–50; requires role when > 0
+  readonly actionLogLineRole?: IRole;
+  readonly alarmActions?: IAlarmAction[];


Should we have default values for these as well or we can mark default none ? We can follow what is being followed for metric alarm. Same goes for other optional parameters like actionLogLineRole

chintan-vaghani2008 · 2026-07-08T11:03:14Z

+  readonly actionsEnabled?: boolean;                     // @default true
+  readonly treatMissingData?: TreatMissingData;          // @default - service default
+  readonly actionLogLineCount?: number;                  // 0–50
+  readonly actionLogLineRole?: IRole;                    // auto-created (trusts cloudwatch.amazonaws.com) when count > 0


Do you mean auto created only when not passed ? Also, we plan to auto create it , would we have all required parameters in place to auto create it ? Let's also see what further reviewer has take on this.

chintan-vaghani2008 · 2026-07-08T11:04:36Z

+
+### Why should we _not_ do this?
+
+There is no strong reason not to. The `ScheduledQueryConfiguration` field constraints are final (`logGroupIdentifiers`


Do we have to mention this now given we are going with what will be the final spec?

The ScheduledQueryConfiguration field constraints are final (logGroupIdentifiers
is optional, and the startTimeOffset range is fixed), and the construct tracks the published
@aws-cdk/aws-service-spec

chintan-vaghani2008 · 2026-07-08T11:05:57Z

+
+### Are there any open issues that need to be addressed later?
+
+- None. The `ScheduledQueryConfiguration` field constraints are final; the L2 tracks the published


Again, we may not have to mention this "The ScheduledQueryConfiguration field constraints are final; the L2 tracks the published @aws-cdk/aws-service-spec for the AWS::CloudWatch::LogAlarm schema." unless needed. It will confuse the reviewer further.

chintan-vaghani2008 · 2026-07-09T13:29:38Z

Changes now looks good to me.

- logGroups accepts ILogGroupRef[] instead of logGroupIdentifiers: string[]; correct the circular-dependency rationale (ILogGroupRef lives in the shared generated interface layer and is already used cross-module) - document IAM role behaviour: roles are created when omitted and never mutated when supplied; explain why addLogGroup() is not offered - document scheduled query observability and why no metric*() helpers - align the synth validation list with the implemented checks - fix author handle and the actionLogLineRole auto-creation wording

Follows the Roles section of the CDK Design Guidelines and the Function / StateMachine / Project / DeliveryStream precedent: the construct grants the permissions the feature needs to whichever role is in use, created or supplied, scoped to the log groups in logGroups. Trust is still not modified on a supplied role. Callers who need an untouched role use Role.fromRoleArn with mutable: false, and addToRolePolicy is exposed per the guidelines.

matboros

lgtm

mergify · 2026-08-31T10:33:18Z

Thank you for contributing! Your pull request is now being automatically merged.

mergify · 2026-08-31T10:33:21Z

rodrigotuna force-pushed the logalarm-l2 branch from 1ac7c43 to 0fcf157 Compare July 3, 2026 15:50

chintan-vaghani2008 reviewed Jul 7, 2026

View reviewed changes

rodrigotuna force-pushed the logalarm-l2 branch from b63650a to 0ebb4a6 Compare July 7, 2026 17:33

chintan-vaghani2008 reviewed Jul 8, 2026

View reviewed changes

RFC: Log Alarm L2 Construct (aws#960)

0ddd64f

rodrigotuna force-pushed the logalarm-l2 branch from 0ebb4a6 to 0ddd64f Compare July 9, 2026 11:00

chintan-vaghani2008 approved these changes Jul 9, 2026

View reviewed changes

matboros requested changes Aug 24, 2026

View reviewed changes

Comment thread text/0960-logalarm-l2.md Outdated

Comment thread text/0960-logalarm-l2.md

Comment thread text/0960-logalarm-l2.md

Comment thread text/0960-logalarm-l2.md Outdated

Comment thread text/0960-logalarm-l2.md Outdated

matboros requested changes Aug 27, 2026

View reviewed changes

Comment thread text/0960-logalarm-l2.md

matboros approved these changes Aug 31, 2026

View reviewed changes

mergify Bot added the queued label Aug 31, 2026

mergify Bot mentioned this pull request Aug 31, 2026

merge queue: checking #962 on main (7d8a862) #991

Closed

18 tasks

mergify Bot merged commit 9fb5468 into aws:main Aug 31, 2026
4 checks passed

mergify Bot removed the queued label Aug 31, 2026


		### Why should we _not_ do this?

		There is no strong reason not to. The `ScheduledQueryConfiguration` field constraints are final (`logGroupIdentifiers`


		### Are there any open issues that need to be addressed later?

		- None. The `ScheduledQueryConfiguration` field constraints are final; the L2 tracks the published

Conversation

rodrigotuna commented Jul 3, 2026

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

chintan-vaghani2008 commented Jul 9, 2026

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

matboros left a comment

Choose a reason for hiding this comment

Uh oh!

mergify Bot commented Aug 31, 2026

Uh oh!

mergify Bot commented Aug 31, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Merge Queue Status

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

mergify Bot commented Aug 31, 2026 •

edited

Loading