async-lambda-unstable 0.6.13__tar.gz → 0.6.14__tar.gz

{async_lambda_unstable-0.6.13 → async_lambda_unstable-0.6.14}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: async-lambda-unstable
-Version: 0.6.13
+Version: 0.6.14
 Summary: A framework for creating AWS Lambda Async Workflows. - Unstable Branch
 Author-email: "Nuclei, Inc" <engineering@nuclei.ai>
 Requires-Dist: click>=8.0.0
@@ -437,6 +437,27 @@ Two caveats:
 - A task with task-specific `policies` keeps its own generated role, since the shared role is built from app-wide and stage-wide config only.
 - Every app-wide policy must be either a managed policy ARN or a `{"Statement": [...]}` document. SAM policy templates can't be expressed in a plain IAM role and will fail the build.
 
+### Consolidated Queue-Age Alarms
+
+`managed_queue_extras` attaches a copy of each extra resource to *every* managed queue, so using it for a CloudWatch alarm costs one stack resource per queue lane.
+
+Setting `queue_age_alarm` in the build config emits a small number of grouped alarms instead, each watching `ApproximateAgeOfOldestMessage` across up to ten queues:
+
+```json
+{
+  "queue_age_alarm": {
+    "threshold": 5000,
+    "period": 86400,
+    "alarm_actions": ["arn:aws:sns:us-east-1:123456789012:alarms"],
+    "ok_actions": ["arn:aws:sns:us-east-1:123456789012:alarms"]
+  }
+}
+```
+
+Only `threshold` is required and `period` defaults to one day. Coverage is every managed queue lane plus the app DLQ. An app with 104 queues gets 11 alarms rather than 104.
+
+CloudWatch rejects an alarm carrying more than 10 metrics.
+
 ## Known Limitations
 
 - Not all Lambda configuration options are supported (see code for extension points)

{async_lambda_unstable-0.6.13 → async_lambda_unstable-0.6.14}/README.md

@@ -425,6 +425,27 @@ Two caveats:
 - A task with task-specific `policies` keeps its own generated role, since the shared role is built from app-wide and stage-wide config only.
 - Every app-wide policy must be either a managed policy ARN or a `{"Statement": [...]}` document. SAM policy templates can't be expressed in a plain IAM role and will fail the build.
 
+### Consolidated Queue-Age Alarms
+
+`managed_queue_extras` attaches a copy of each extra resource to *every* managed queue, so using it for a CloudWatch alarm costs one stack resource per queue lane.
+
+Setting `queue_age_alarm` in the build config emits a small number of grouped alarms instead, each watching `ApproximateAgeOfOldestMessage` across up to ten queues:
+
+```json
+{
+  "queue_age_alarm": {
+    "threshold": 5000,
+    "period": 86400,
+    "alarm_actions": ["arn:aws:sns:us-east-1:123456789012:alarms"],
+    "ok_actions": ["arn:aws:sns:us-east-1:123456789012:alarms"]
+  }
+}
+```
+
+Only `threshold` is required and `period` defaults to one day. Coverage is every managed queue lane plus the app DLQ. An app with 104 queues gets 11 alarms rather than 104.
+
+CloudWatch rejects an alarm carrying more than 10 metrics.
+
 ## Known Limitations
 
 - Not all Lambda configuration options are supported (see code for extension points)

{async_lambda_unstable-0.6.13 → async_lambda_unstable-0.6.14}/async_lambda/__init__.py

@@ -22,4 +22,4 @@ from .models.events.managed_sqs_event import ManagedSQSEvent as ManagedSQSEvent
 from .models.events.scheduled_event import ScheduledEvent as ScheduledEvent
 from .models.events.unmanaged_sqs_event import UnmanagedSQSEvent as UnmanagedSQSEvent
 
-__version__ = "0.6.13"
+__version__ = "0.6.14"

{async_lambda_unstable-0.6.13 → async_lambda_unstable-0.6.14}/async_lambda/build_config.py

@@ -14,6 +14,46 @@ def make_default_tags() -> Dict[str, str]:
     return {"framework": "async-lambda", "framework-version": __version__}
 
 
+@dataclass
+class QueueAgeAlarmConfig:
+    """
+    Settings for the consolidated queue-age alarms.
+
+    One alarm covers a group of queues rather than one alarm per queue.
+
+    Attributes:
+        threshold (int): Oldest-message age, in seconds, above which the alarm fires.
+        period (int): Seconds of data each datapoint covers.
+        alarm_actions (List[str]): ARNs notified when an alarm starts firing.
+        ok_actions (List[str]): ARNs notified when an alarm recovers.
+    """
+
+    threshold: int
+    period: int
+    alarm_actions: List[str]
+    ok_actions: List[str]
+
+    @classmethod
+    def new(cls, config: dict) -> "QueueAgeAlarmConfig":
+        """
+        Creates a new instance from a configuration dictionary.
+
+        Args:
+            config (dict): provided the values of QueueAgeAlarmConfig
+
+        Returns:
+            QueueAgeAlarmConfig: A new instance configured with the provided options.
+        """
+        if "threshold" not in config:
+            raise ValueError("queue_age_alarm requires a `threshold`.")
+        return cls(
+            threshold=config["threshold"],
+            period=config.get("period", 86400),
+            alarm_actions=list(config.get("alarm_actions", list())),
+            ok_actions=list(config.get("ok_actions", list())),
+        )
+
+
 @dataclass
 class AsyncLambdaBuildConfig:
     """
@@ -26,6 +66,7 @@ class AsyncLambdaBuildConfig:
         subnet_ids (Set[str]): Set of subnet IDs for VPC configuration.
         security_group_ids (Set[str]): Set of security group IDs for VPC configuration.
         managed_queue_extras (List[dict]): Additional configuration for managed queues.
+        queue_age_alarm (Optional[QueueAgeAlarmConfig]): Settings for the consolidated queue-age alarms. No alarms are emitted when this is unset.
         method_settings (List[dict]): API Gateway method settings.
         tags (Dict[str, str]): Tags to assign to the Lambda function.
         logging_config (Dict[str, str]): Logging configuration options.
@@ -57,6 +98,7 @@ class AsyncLambdaBuildConfig:
     certificate_arn: Optional[str] = None
     hosted_zone_id: Optional[str] = None
     auto_create_acm_certificate: Optional[bool] = None
+    queue_age_alarm: Optional[QueueAgeAlarmConfig] = None
 
     @classmethod
     def new(cls, config: dict) -> "AsyncLambdaBuildConfig":
@@ -71,6 +113,7 @@ class AsyncLambdaBuildConfig:
                 - subnet_ids (set or list): Set or list of subnet IDs for VPC configuration.
                 - security_group_ids (set or list): Set or list of security group IDs for VPC configuration.
                 - managed_queue_extras (list): Additional managed queue configuration.
+                - queue_age_alarm (dict): Settings for the consolidated queue-age alarms.
                 - method_settings (list): List of method settings for API Gateway.
                 - tags (dict): Tags to assign to the Lambda function.
                 - logging_config (dict): Logging configuration options.
@@ -89,6 +132,11 @@ class AsyncLambdaBuildConfig:
             subnet_ids=set(config.get("subnet_ids", set())),
             security_group_ids=set(config.get("security_group_ids", set())),
             managed_queue_extras=list(config.get("managed_queue_extras", list())),
+            queue_age_alarm=(
+                QueueAgeAlarmConfig.new(config["queue_age_alarm"])
+                if config.get("queue_age_alarm") is not None
+                else None
+            ),
             method_settings=list(config.get("method_settings", list())),
             tags=config.get("tags", dict()),
             logging_config=config.get("logging_config", dict()),
@@ -118,6 +166,8 @@ class AsyncLambdaBuildConfig:
             self.hosted_zone_id = other.hosted_zone_id
         if other.auto_create_acm_certificate is not None:
             self.auto_create_acm_certificate = other.auto_create_acm_certificate
+        if other.queue_age_alarm is not None:
+            self.queue_age_alarm = other.queue_age_alarm
 
     @property
     def function_properties(self):

{async_lambda_unstable-0.6.13 → async_lambda_unstable-0.6.14}/async_lambda/controller.py

@@ -20,7 +20,11 @@ from typing import (
 from uuid import uuid4
 
 from . import env
-from .build_config import AsyncLambdaBuildConfig, get_build_config_for_stage
+from .build_config import (
+    AsyncLambdaBuildConfig,
+    QueueAgeAlarmConfig,
+    get_build_config_for_stage,
+)
 from .client import get_s3_client, get_scheduler_client, get_sqs_client
 from .config import config
 from .middleware import MET, RT, MiddlewareFunction, MiddlewareRegistration
@@ -46,6 +50,9 @@ logger = logging.getLogger(__name__)
 
 _SQS_MAX_DELAY_SECONDS = 900
 
+# CloudWatch rejects an alarm carrying more than 10 metrics.
+_MAX_METRICS_PER_ALARM = 10
+
 BaseEventT = TypeVar("BaseEventT", bound=BaseEvent)
 APIEventT = TypeVar("APIEventT", bound=APIEvent)
 ManagedSQSEventT = TypeVar("ManagedSQSEventT", bound=ManagedSQSEvent)
@@ -231,6 +238,92 @@ class AsyncLambdaController:
             + f"{config.name}-*"
         }
 
+    def _alarmable_queue_logical_ids(self) -> List[str]:
+        """
+        Logical IDs of every queue the queue-age alarms should watch.
+
+        Covers each managed queue lane plus the app DLQ. The delay DLQ is left out
+        because it is named deterministically and so can be alarmed on directly.
+        """
+        logical_ids = []
+        for task in self.tasks.values():
+            if task.trigger_type not in MANAGED_SQS_TASK_TYPES:
+                continue
+            for lane_index in range(task.get_lane_count()):
+                logical_ids.append(task.get_managed_queue_logical_id(lane=lane_index))
+        logical_ids.append("AsyncLambdaDLQ")
+        return logical_ids
+
+    @staticmethod
+    def _build_queue_age_alarms(
+        queue_logical_ids: List[str],
+        alarm_config: QueueAgeAlarmConfig,
+    ) -> Dict[str, dict]:
+        """
+        Builds alarms watching the oldest message age across every managed queue.
+
+        Queues are grouped rather than alarmed individually.
+
+        Each alarm watches `MAX(METRICS())` over its own group. `METRICS()` resolves to just that alarm's
+        metrics.
+
+        Grouping is required because CloudWatch caps an alarm at 10 metrics.
+        """
+        alarms = {}
+        for alarm_index, group_start in enumerate(
+            range(0, len(queue_logical_ids), _MAX_METRICS_PER_ALARM)
+        ):
+            group = queue_logical_ids[
+                group_start : group_start + _MAX_METRICS_PER_ALARM
+            ]
+            metrics: List[dict] = [
+                {
+                    "Id": f"q{metric_index}",
+                    "ReturnData": False,
+                    "MetricStat": {
+                        "Metric": {
+                            "Namespace": "AWS/SQS",
+                            "MetricName": "ApproximateAgeOfOldestMessage",
+                            "Dimensions": [
+                                {
+                                    "Name": "QueueName",
+                                    "Value": {
+                                        "Fn::GetAtt": [queue_logical_id, "QueueName"]
+                                    },
+                                }
+                            ],
+                        },
+                        "Period": alarm_config.period,
+                        "Stat": "Maximum",
+                    },
+                }
+                for metric_index, queue_logical_id in enumerate(group)
+            ]
+            metrics.append(
+                {
+                    "Id": "oldest_message_age",
+                    "Expression": "MAX(METRICS())",
+                    "ReturnData": True,
+                }
+            )
+            alarms[f"AsyncLambdaQueueAgeAlarm{alarm_index}"] = {
+                "Type": "AWS::CloudWatch::Alarm",
+                "Properties": {
+                    "ActionsEnabled": True,
+                    "AlarmActions": alarm_config.alarm_actions,
+                    "OKActions": alarm_config.ok_actions,
+                    "AlarmDescription": (
+                        f"Oldest message age across {len(group)} {config.name} queues"
+                    ),
+                    "ComparisonOperator": "GreaterThanThreshold",
+                    "EvaluationPeriods": 1,
+                    "Metrics": metrics,
+                    "Threshold": alarm_config.threshold,
+                    "TreatMissingData": "notBreaching",
+                },
+            }
+        return alarms
+
     @classmethod
     def _build_shared_function_role(
         cls,
@@ -744,6 +837,14 @@ class AsyncLambdaController:
                 self._dlq_extras_replace_references(extra)
             )
 
+        if build_config.queue_age_alarm is not None:
+            template["Resources"].update(
+                self._build_queue_age_alarms(
+                    queue_logical_ids=self._alarmable_queue_logical_ids(),
+                    alarm_config=build_config.queue_age_alarm,
+                )
+            )
+
         if has_api_tasks:
             properties: dict = {
                 "StageName": "prod",