From 0615aa5b775f979b08762f2806e53059bf4d6e79 Mon Sep 17 00:00:00 2001
From: Adam Moussa <166072409+amoussa1229@users.noreply.github.com>
Date: Wed, 17 Jun 2026 17:28:42 -0400
Subject: [PATCH] Add CloudWatch alarm for po-email-processor DLQ messages
 (#69)

Page when any message lands in the EmailProcessorDlq, which means a PO
email was permanently dropped after po-email-processor exhausted its
async Lambda retries. Without this, the errors alarm catches the failing
invocations but nothing surfaces the resulting dead-lettered email.

AWS/SQS ApproximateNumberOfMessagesVisible, Maximum over a single 5-min
period > 0, notBreaching on missing data. Reuses the shared site-alerts
SNS topic, ALARM-only, matching the existing po-email-processor-errors
alarm. The metric helper derives the QueueName dimension from the queue
construct (Fn::GetAtt QueueName), so the alarm tracks the CDK-generated
queue name without hardcoding it.
---
 cdk/po_stack.py | 22 ++++++++++++++++++++++
 1 file changed, 22 insertions(+)

diff --git a/cdk/po_stack.py b/cdk/po_stack.py
index ee30ecc..4648842 100644
--- a/cdk/po_stack.py
+++ b/cdk/po_stack.py
@@ -227,6 +227,28 @@ class PoIngestStack(Stack):
             treat_missing_data=cloudwatch.TreatMissingData.NOT_BREACHING,
         ).add_alarm_action(cw_actions.SnsAction(alarm_topic))
 
+        # --- DLQ messages-present alarm ---
+        # Pages when any message lands in the EmailProcessorDlq: a message here
+        # means a PO email was permanently dropped after Lambda exhausted its
+        # async retries. Maximum over a single 5-min window > 0 fires; missing
+        # data (no messages metric emitted) is not breaching. Reuses the shared
+        # site-alerts topic, ALARM-only, like the errors alarm above. The metric
+        # helper derives the QueueName dimension from the queue construct, so the
+        # alarm tracks the CDK-generated queue name without hardcoding it.
+        email_processor_dlq.metric_approximate_number_of_messages_visible(
+            period=Duration.minutes(5),
+            statistic="Maximum",
+        ).create_alarm(
+            self,
+            "EmailProcessorDlqMessagesAlarm",
+            alarm_name="po-email-processor-dlq-messages",
+            alarm_description="po-email-processor DLQ has messages (dropped PO emails)",
+            threshold=0,
+            evaluation_periods=1,
+            comparison_operator=cloudwatch.ComparisonOperator.GREATER_THAN_THRESHOLD,
+            treat_missing_data=cloudwatch.TreatMissingData.NOT_BREACHING,
+        ).add_alarm_action(cw_actions.SnsAction(alarm_topic))
+
         # --- Duration alarm: po-email-processor (orphan adoption) ---
         # Adopts the orphaned CLI alarm Lambda-Duration-po-email-processor under
         # the repo's <fn>-duration naming (NEW logical name → no deploy collision;