chore(sqs): note that incoming messages alarm does not capture messages sent to DLQ due to failed processing attempts (#117)

Closes #109

---

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

Author: Eugene Cheung

API.md

@@ -7123,7 +7123,7 @@ const baseDlqAlarms: BaseDlqAlarms = { ... }
 
 | **Name** | **Type** | **Description** |
 | --- | --- | --- |
-| <code><a href="#cdk-monitoring-constructs.BaseDlqAlarms.property.addDeadLetterQueueMaxIncomingMessagesAlarm">addDeadLetterQueueMaxIncomingMessagesAlarm</a></code> | <code>{[ key: string ]: <a href="#cdk-monitoring-constructs.MaxIncomingMessagesCountThreshold">MaxIncomingMessagesCountThreshold</a>}</code> | *No description.* |
+| <code><a href="#cdk-monitoring-constructs.BaseDlqAlarms.property.addDeadLetterQueueMaxIncomingMessagesAlarm">addDeadLetterQueueMaxIncomingMessagesAlarm</a></code> | <code>{[ key: string ]: <a href="#cdk-monitoring-constructs.MaxIncomingMessagesCountThreshold">MaxIncomingMessagesCountThreshold</a>}</code> | Alarm on the number of messages added to a queue. |
 | <code><a href="#cdk-monitoring-constructs.BaseDlqAlarms.property.addDeadLetterQueueMaxMessageAgeAlarm">addDeadLetterQueueMaxMessageAgeAlarm</a></code> | <code>{[ key: string ]: <a href="#cdk-monitoring-constructs.MaxMessageAgeThreshold">MaxMessageAgeThreshold</a>}</code> | *No description.* |
 | <code><a href="#cdk-monitoring-constructs.BaseDlqAlarms.property.addDeadLetterQueueMaxSizeAlarm">addDeadLetterQueueMaxSizeAlarm</a></code> | <code>{[ key: string ]: <a href="#cdk-monitoring-constructs.MaxMessageCountThreshold">MaxMessageCountThreshold</a>}</code> | *No description.* |
 
@@ -7137,6 +7137,13 @@ public readonly addDeadLetterQueueMaxIncomingMessagesAlarm: {[ key: string ]: Ma
 
 - *Type:* {[ key: string ]: <a href="#cdk-monitoring-constructs.MaxIncomingMessagesCountThreshold">MaxIncomingMessagesCountThreshold</a>}
 
+Alarm on the number of messages added to a queue.
+
+Note that this corresponds with the NumberOfMessagesSent metric, which does not capture messages sent to the DLQ
+as a result of a failed processing attempt.
+
+> [https://docs.aws.amazon.com/AWSSimpleQueueService/latest/SQSDeveloperGuide/sqs-dead-letter-queues.html#sqs-dlq-number-of-messages](https://docs.aws.amazon.com/AWSSimpleQueueService/latest/SQSDeveloperGuide/sqs-dead-letter-queues.html#sqs-dlq-number-of-messages)
+
 ---
 
 ##### `addDeadLetterQueueMaxMessageAgeAlarm`<sup>Optional</sup> <a name="addDeadLetterQueueMaxMessageAgeAlarm" id="cdk-monitoring-constructs.BaseDlqAlarms.property.addDeadLetterQueueMaxMessageAgeAlarm"></a>
@@ -31015,7 +31022,7 @@ const sqsQueueMonitoringWithDlqProps: SqsQueueMonitoringWithDlqProps = { ... }
 | <code><a href="#cdk-monitoring-constructs.SqsQueueMonitoringWithDlqProps.property.addToDetailDashboard">addToDetailDashboard</a></code> | <code>boolean</code> | Flag indicating if the widgets should be added to detailed dashboard. |
 | <code><a href="#cdk-monitoring-constructs.SqsQueueMonitoringWithDlqProps.property.addToSummaryDashboard">addToSummaryDashboard</a></code> | <code>boolean</code> | Flag indicating if the widgets should be added to summary dashboard. |
 | <code><a href="#cdk-monitoring-constructs.SqsQueueMonitoringWithDlqProps.property.useCreatedAlarms">useCreatedAlarms</a></code> | <code><a href="#cdk-monitoring-constructs.IAlarmConsumer">IAlarmConsumer</a></code> | Calls provided function to process all alarms created. |
-| <code><a href="#cdk-monitoring-constructs.SqsQueueMonitoringWithDlqProps.property.addDeadLetterQueueMaxIncomingMessagesAlarm">addDeadLetterQueueMaxIncomingMessagesAlarm</a></code> | <code>{[ key: string ]: <a href="#cdk-monitoring-constructs.MaxIncomingMessagesCountThreshold">MaxIncomingMessagesCountThreshold</a>}</code> | *No description.* |
+| <code><a href="#cdk-monitoring-constructs.SqsQueueMonitoringWithDlqProps.property.addDeadLetterQueueMaxIncomingMessagesAlarm">addDeadLetterQueueMaxIncomingMessagesAlarm</a></code> | <code>{[ key: string ]: <a href="#cdk-monitoring-constructs.MaxIncomingMessagesCountThreshold">MaxIncomingMessagesCountThreshold</a>}</code> | Alarm on the number of messages added to a queue. |
 | <code><a href="#cdk-monitoring-constructs.SqsQueueMonitoringWithDlqProps.property.addDeadLetterQueueMaxMessageAgeAlarm">addDeadLetterQueueMaxMessageAgeAlarm</a></code> | <code>{[ key: string ]: <a href="#cdk-monitoring-constructs.MaxMessageAgeThreshold">MaxMessageAgeThreshold</a>}</code> | *No description.* |
 | <code><a href="#cdk-monitoring-constructs.SqsQueueMonitoringWithDlqProps.property.addDeadLetterQueueMaxSizeAlarm">addDeadLetterQueueMaxSizeAlarm</a></code> | <code>{[ key: string ]: <a href="#cdk-monitoring-constructs.MaxMessageCountThreshold">MaxMessageCountThreshold</a>}</code> | *No description.* |
 | <code><a href="#cdk-monitoring-constructs.SqsQueueMonitoringWithDlqProps.property.deadLetterQueue">deadLetterQueue</a></code> | <code>aws-cdk-lib.aws_sqs.IQueue</code> | *No description.* |
@@ -31199,6 +31206,13 @@ public readonly addDeadLetterQueueMaxIncomingMessagesAlarm: {[ key: string ]: Ma
 
 - *Type:* {[ key: string ]: <a href="#cdk-monitoring-constructs.MaxIncomingMessagesCountThreshold">MaxIncomingMessagesCountThreshold</a>}
 
+Alarm on the number of messages added to a queue.
+
+Note that this corresponds with the NumberOfMessagesSent metric, which does not capture messages sent to the DLQ
+as a result of a failed processing attempt.
+
+> [https://docs.aws.amazon.com/AWSSimpleQueueService/latest/SQSDeveloperGuide/sqs-dead-letter-queues.html#sqs-dlq-number-of-messages](https://docs.aws.amazon.com/AWSSimpleQueueService/latest/SQSDeveloperGuide/sqs-dead-letter-queues.html#sqs-dlq-number-of-messages)
+
 ---
 
 ##### `addDeadLetterQueueMaxMessageAgeAlarm`<sup>Optional</sup> <a name="addDeadLetterQueueMaxMessageAgeAlarm" id="cdk-monitoring-constructs.SqsQueueMonitoringWithDlqProps.property.addDeadLetterQueueMaxMessageAgeAlarm"></a>

lib/monitoring/aws-sqs/SqsQueueMonitoringWithDlq.ts

@@ -33,10 +33,20 @@ export interface BaseDlqAlarms {
     string,
     MaxMessageCountThreshold
   >;
+
   readonly addDeadLetterQueueMaxMessageAgeAlarm?: Record<
     string,
     MaxMessageAgeThreshold
   >;
+
+  /**
+   * Alarm on the number of messages added to a queue.
+   *
+   * Note that this corresponds with the NumberOfMessagesSent metric, which does not capture messages sent to the DLQ
+   * as a result of a failed processing attempt.
+   *
+   * @see https://docs.aws.amazon.com/AWSSimpleQueueService/latest/SQSDeveloperGuide/sqs-dead-letter-queues.html#sqs-dlq-number-of-messages
+   */
   readonly addDeadLetterQueueMaxIncomingMessagesAlarm?: Record<
     string,
     MaxIncomingMessagesCountThreshold
@@ -47,6 +57,7 @@ export interface SqsQueueMonitoringWithDlqProps
   extends SqsQueueMonitoringProps,
     BaseDlqAlarms {
   readonly deadLetterQueue: IQueue;
+
   /**
    * Indicates whether the DLQ monitoring should be added to summary dashboard.
    *