AWS AWSSimpleQueueService documentation change
Summary
Restructured and expanded CloudWatch metrics documentation with detailed metric descriptions, reporting behavior, and monitoring tips. Added new sections explaining metric nuances like poison-pill message handling, DLQ behavior, and FIFO queue considerations.
Security assessment
The changes focus on improving operational monitoring guidance and metric explanations. While they mention DLQs and message lifecycle management, there is no evidence of addressing security vulnerabilities or documenting new security features. The updates are operational/observability improvements rather than security-related.
Diff
diff --git a/AWSSimpleQueueService/latest/SQSDeveloperGuide/sqs-available-cloudwatch-metrics.md b/AWSSimpleQueueService/latest/SQSDeveloperGuide/sqs-available-cloudwatch-metrics.md index f29509011..e504363f0 100644 --- a//AWSSimpleQueueService/latest/SQSDeveloperGuide/sqs-available-cloudwatch-metrics.md +++ b//AWSSimpleQueueService/latest/SQSDeveloperGuide/sqs-available-cloudwatch-metrics.md @@ -5 +5 @@ -Amazon SQS metricsDead-letter queues (DLQs) and CloudWatch metricsDimensions for Amazon SQS metrics +Amazon SQS metricsDead-letter queues (DLQs) and CloudWatch metricsDimensions for Amazon SQS metricsMonitoring tips @@ -17,5 +17 @@ For some metrics, the result is approximate because of the distributed architect -The `AWS/SQS` namespace includes the following metrics. - -Metric | Description ----|--- -`ApproximateAgeOfOldestMessage` | The approximate age of the oldest non-deleted message in the queue. +Amazon SQS automatically publishes operational metrics to [Amazon CloudWatch](https://docs.aws.amazon.com/AmazonCloudWatch/latest/monitoring/WhatIsCloudWatch.html) under the `AWS/SQS` namespace. These metrics help you monitor queue health and performance. Due to SQS’s distributed nature, many values are approximate, but accurate enough for most operational decisions. @@ -25,4 +21 @@ Metric | Description - * After a message is received three times (or more) and not processed, the message is moved to the back of the queue and the `ApproximateAgeOfOldestMessage` metric points to the second-oldest message that hasn't been received more than three times. This action occurs even if the queue has a redrive policy. - * Because a single "poison-pill" message (received multiple times but never deleted) can distort this metric, the age of such a message isn't included until it is consumed successfully. - * When the queue has a redrive policy, the message is moved to a [dead-letter queue (DLQ)](./sqs-dead-letter-queues.html) after the configured maximum number of receives. When the message is moved to the DLQ, the `ApproximateAgeOfOldestMessage` metric of the DLQ represents the time when the message was moved to the DLQ, not the original time the message was sent. - * For FIFO queues, the message is not moved to the back of the queue because this will break the FIFO order guarantee. Instead, the message goes to the DLQ if one is configured; otherwise, it will block the message group until successfully deleted or until it expires. + * All metrics emit non-negative values only when the queue is active. @@ -30,8 +23 @@ Metric | Description -**Reporting criteria:** A non-negative value is reported [if the queue is active](./monitoring-using-cloudwatch.html).**Units:** Seconds**Valid statistics:** Average, Minimum, Maximum, Sum, Data Samples (displays as Sample Count in the Amazon SQS console) -`ApproximateNumberOfGroupsWithInflightMessages` | The approximate number of message groups with in flight messages, where a message is considered to be _in flight_ after it's received from a queue by a consumer, but not yet deleted from the queue. This metric can help you troubleshoot and optimize your FIFO queue throughput by either increasing FIFO message groups, or scaling your consumers. **Reporting criteria:** A non-negative value is reported [if the queue is active](./monitoring-using-cloudwatch.html).**Units:** Count**Valid statistics:** Average, Minimum, Maximum, Sum, Data Samples (displays as Sample Count in the Amazon SQS console) For current FIFO throughput and in flight limits, see [Amazon SQS message quotas](./quotas-messages.html). -`ApproximateNumberOfMessagesDelayed` | The number of messages in the queue that are delayed and not available for reading immediately. This can happen when the queue is configured as a delay queue or when a message has been sent with a delay parameter. **Reporting criteria:** A non-negative value is reported [if the queue is active](./monitoring-using-cloudwatch.html).**Units:** Count**Valid statistics:** Average, Minimum, Maximum, Sum, Data Samples (displays as Sample Count in the Amazon SQS console) -`ApproximateNumberOfMessagesNotVisible` | The number of messages that are in flight. Messages are considered to be _in flight_ if they have been sent to a client but have not yet been deleted or have not yet reached the end of their visibility window.**Reporting criteria:** A non-negative value is reported [if the queue is active](./monitoring-using-cloudwatch.html).**Units:** Count**Valid statistics:** Average, Minimum, Maximum, Sum, Data Samples (displays as Sample Count in the Amazon SQS console) -`ApproximateNumberOfMessagesVisible` | The number of messages to be processed. **Reporting criteria:** A non-negative value is reported [if the queue is active](./monitoring-using-cloudwatch.html).**Units:** Count**Valid statistics:** Average, Minimum, Maximum, Sum, Data Samples (displays as Sample Count in the Amazon SQS console)There is no limit on the number of messages to processes, however you can subject this backlog to a retention period. -`NumberOfEmptyReceives`¹ | The number of `ReceiveMessage` API calls that did not return a message.**Reporting criteria:** A non-negative value is reported [if the queue is active](./monitoring-using-cloudwatch.html).**Units:** Count**Valid statistics:** Average, Minimum, Maximum, Sum, Data Samples (displays as Sample Count in the Amazon SQS console) -`NumberOfDeduplicatedSentMessages` | The number of messages sent to a queue that were deduplicated. This metric can help determine if a producer is sending duplicate messages to an Amazon SQS FIFO queue.**Reporting criteria:** A non-negative value is reported [if the queue is active](./monitoring-using-cloudwatch.html).**Units:** Count**Valid statistics:** Average, Minimum, Maximum, Sum, Data Samples (displays as Sample Count in the Amazon SQS console) -`NumberOfMessagesDeleted`¹ | The number of messages deleted from the queue.**Reporting criteria:** A non-negative value is reported [if the queue is active](./monitoring-using-cloudwatch.html).**Units:** Count**Valid statistics:** Average, Minimum, Maximum, Sum, Data Samples (displays as Sample Count in the Amazon SQS console)Amazon SQS emits the `NumberOfMessagesDeleted` metric for every successful deletion operation that uses a valid [ receipt handle](https://docs.aws.amazon.com/AWSSimpleQueueService/latest/SQSDeveloperGuide/sqs-queue-message-identifiers.html#receipt-handle), including duplicate deletions. The following scenarios might cause the value of the `NumberOfMessagesDeleted` metric to be higher than expected: + * Some metrics (such as `SentMessageSize`) are not emitted until at least one message is sent. @@ -39,2 +24,0 @@ Metric | Description - * Calling the `DeleteMessage` action on different receipt handles that belong to the same message: If the message is not processed before the [visibility timeout](https://docs.aws.amazon.com/AWSSimpleQueueService/latest/SQSDeveloperGuide/sqs-visibility-timeout.html) expires, the message becomes available to other consumers that can process it and delete it again, increasing the value of the `NumberOfMessagesDeleted` metric. - * Calling the `DeleteMessage` action on the same receipt handle: If the message is processed and deleted but you call the `DeleteMessage` action again using the same receipt handle, a success status is returned, increasing the value of the `NumberOfMessagesDeleted` metric. @@ -43,3 +26,0 @@ Metric | Description -`NumberOfMessagesReceived`¹ | The number of messages returned by calls to the `ReceiveMessage` action.**Reporting criteria:** A non-negative value is reported [if the queue is active](./monitoring-using-cloudwatch.html).**Units:** Count**Valid statistics:** Average, Minimum, Maximum, Sum, Data Samples (displays as Sample Count in the Amazon SQS console) -`NumberOfMessagesSent`¹ | The number of messages added to a queue. If you send a message to a DLQ manually, it is captured by the `NumberOfMessagesSent` metric. However, if a message is sent to a DLQ as a result of a failed processing attempt (for example, automatically moved due to exceeding the `maxReceiveCount`), it is not captured by this metric. Therefore, it is possible for the values of `NumberOfMessagesSent` and `NumberOfMessagesReceived` to differ.**Reporting criteria:** A non-negative value is reported [if the queue is active](./monitoring-using-cloudwatch.html).**Units:** Count**Valid statistics:** Average, Minimum, Maximum, Sum, Data Samples (displays as Sample Count in the Amazon SQS console) -`SentMessageSize`¹ | The size of messages added to a queue.**Reporting criteria:** A non-negative value is reported [if the queue is active](./monitoring-using-cloudwatch.html).**Units:** Bytes**Valid statistics:** Average, Minimum, Maximum, Sum, Data Samples (displays as Sample Count in the Amazon SQS console) @@ -47 +28,51 @@ Metric | Description -###### Note +Metric | Description | Units | Reporting behavior | Key notes +---|---|---|---|--- +`ApproximateAgeOfOldestMessage` | The age of the oldest unprocessed message in the queue. | Seconds | Reported if the queue contains at least one active message. | + + * For standard queues, if a message is received three or more times and not deleted, SQS moves it to the back of the queue. The metric then reflects the age of the next message that hasn’t exceeded the receive threshold. This reordering occurs even when a redrive policy is in place. + * Poison-pill messages (those repeatedly received but never deleted) are excluded from this metric until successfully processed. + * When a message is moved to a DLQ after exceeding the `maxReceiveCount`, the age resets. In that case, the DLQ’s metric reflects the time the message was moved—not when it was originally sent. + * FIFO queues don't reorder messages to preserve order. A failed message blocks its message group until it's deleted or expires. If a DLQ is configured, the message is sent there after the receive threshold is met. + + +`ApproximateNumberOfGroupsWithInflightMessages` | For FIFO only. The number of message groups with one or more in-flight messages. | Count | Reported if the FIFO queue is active. | + + * A message is considered in-flight after it’s received from the queue by a consumer but not yet deleted or expired. + * This metric helps you troubleshoot and optimize FIFO queue throughput. High values usually indicate strong concurrency. + * If the queue has a large backlog and this value remains low, consider scaling consumers or increasing the number of active message groups. + * For throughput and in-flight limits, see [Amazon SQS quotas](./sqs-quotas.html). + + +`ApproximateNumberOfMessagesDelayed` | The number of messages in the queue that are delayed and not immediately available for retrieval. | Count | Reported if delayed messages exist in the queue. | + + * Applies to queues configured with a default delay and to individual messages sent with a `DelaySeconds` parameter. + * Delayed messages remain hidden from consumers until their delay period expires, which can affect perceived queue backlog or throughput. + + +`ApproximateNumberOfMessagesNotVisible` | The number of in-flight messages that have been received but not yet deleted or expired. | Count | Reported if in-flight messages exist. | + + * Messages enter the in-flight state after being sent to a consumer via the [`ReceiveMessage`](https://docs.aws.amazon.com/AWSSimpleQueueService/latest/APIReference/API_ReceiveMessage.html) API. + * These messages are temporarily hidden from other consumers during the visibility timeout window. + * Use this metric to track message processing delays or stuck consumers. + + +`ApproximateNumberOfMessagesVisible` | The number of messages currently available for retrieval and processing. | Count | Reported if the queue is active. | + + * Reflects the current processing backlog in the queue. + * There's no hard limit on how many messages can accumulate, but they are subject to the queue’s configured [retention period](./welcome.html#sqs-basic-architecture). + * A consistently high value may indicate under-provisioned consumers or stuck processing logic. + + +`NumberOfEmptyReceives`¹ | The number of [ReceiveMessage](https://docs.aws.amazon.com/AWSSimpleQueueService/latest/APIReference/API_ReceiveMessage.html) API calls that returned no messages. | Count | Reported during receive operations. | + + * This metric can help identify inefficiencies in polling behavior or underutilized consumer instances. + * High values may occur when the queue is empty, the consumer uses short polling, or messages are being processed faster than they are produced. + * This isn't a precise indicator of queue state. It reflects service-side behavior and may include retries. + + +`NumberOfDeduplicatedSentMessages` | For FIFO only. The number of sent messages that were deduplicated and not added to the queue. | Count | Reported if duplicate `MessageDeduplicationId` values or content are detected. | + + * SQS deduplicates messages based on the `MessageDeduplicationId` or content-based hashing (if enabled). + * A high value may indicate that a producer is repeatedly sending the same message within the 5-minute deduplication window. + * Use this metric to troubleshoot redundant producer logic or confirm that deduplication is functioning as intended. + @@ -49 +80 @@ Metric | Description -`SentMessageSize` does not display as an available metric in the CloudWatch console until at least one message is sent to the corresponding queue. +`NumberOfMessagesDeleted`¹ | The number of messages successfully deleted from the queue. | Count | Reported for each delete request with a valid receipt handle. | @@ -51 +82,30 @@ Metric | Description -¹ These metrics are calculated from a service perspective, and can include retries. Don't rely on the absolute values of these metrics, or use them to estimate current queue status. + * This metric counts all successful delete operations—even if the same message is deleted more than once. + * Common reasons for higher-than-expected values include: + * Multiple deletes of the same message using different receipt handles, after visibility timeout expires and the message is received again. + * Duplicate deletes using the same receipt handle, which still return a success status and increment the metric. + * Use this metric to track message processing success, but don't treat it as an exact count of unique deleted messages. + + +`NumberOfMessagesReceived`¹ | The number of messages returned by the [ReceiveMessage](https://docs.aws.amazon.com/AWSSimpleQueueService/latest/APIReference/API_ReceiveMessage.html) API. | Count | Reported during receive operations. | + + * This includes all messages returned to consumers, including those that are later returned to the queue due to visibility timeout expiration. + * A single message can be received multiple times if it isn’t deleted, which can cause this metric to exceed the number of messages sent. + * Use this to track consumer activity, but don't treat it as a count of unique messages processed. + + +`NumberOfMessagesSent`¹ | The number of messages successfully added to a queue. | Count | Reported for each successful manual send. | + + * Manual calls to `SendMessage` or `SendMessageBatch` are counted, including those targeting a DLQ directly. + * Messages that are automatically moved to a DLQ after exceeding the `maxReceiveCount` are not included in this metric. + * As a result, `NumberOfMessagesSent` may be lower than `NumberOfMessagesReceived`—especially if redrive policies are moving many messages to DLQs behind the scenes. + + +`SentMessageSize`¹ | The size of messages successfully sent to the queue. | Bytes | Not emitted until at least one message is sent. | + + * This metric will not appear in the CloudWatch console until the queue receives its first message. + * Use this metric to track the size of each message in bytes. This is useful for analyzing payload trends or estimating throughput cost. + * The maximum message size for SQS is 256 KB. + + + +¹ These metrics reflect system-level activity and may include retries, duplicates, or delayed messages. Don’t use raw counts to estimate real-time queue state without factoring in message lifecycle behavior. @@ -57 +117 @@ When working with DLQs, it's important to understand how Amazon SQS metrics beha - * `NumberOfMessagesSent` – This metric behaves differently for DLQs: + * **`NumberOfMessagesSent`** – This metric behaves differently for DLQs: @@ -59 +119 @@ When working with DLQs, it's important to understand how Amazon SQS metrics beha - * Manual Sending – Messages manually sent to a DLQ are captured by this metric. + * **Manual Sending** – Messages manually sent to a DLQ are captured by this metric. @@ -61 +121 @@ When working with DLQs, it's important to understand how Amazon SQS metrics beha - * Automatic Redrive – Messages automatically moved to a DLQ due to processing failures are **not** captured by this metric. As a result, the `NumberOfMessagesSent` and `NumberOfMessagesReceived` metrics may show discrepancies for DLQs. + * **Automatic Redrive** – Messages automatically moved to a DLQ due to processing failures are **not** captured by this metric. As a result, the `NumberOfMessagesSent` and `NumberOfMessagesReceived` metrics may show discrepancies for DLQs. @@ -70 +130,16 @@ When working with DLQs, it's important to understand how Amazon SQS metrics beha -The only dimension that Amazon SQS sends to CloudWatch is `QueueName`. This means that all available statistics are filtered by `QueueName`. +Amazon SQS metrics in CloudWatch use a single dimension: **`QueueName`**. All metric data is grouped and filtered by the name of the queue. + +## Monitoring tips + +Monitor SQS effectively using key metrics and CloudWatch alarms to detect queue backlogs, optimize performance, and stay within service limits. + + * Set [CloudWatch alarms](https://docs.aws.amazon.com/AmazonCloudWatch/latest/monitoring/AlarmThatSendsEmail.html) based on `ApproximateNumberOfMessagesVisible` to catch backlog growth. + + * Monitor `NumberOfEmptyReceives` to tune poll frequency and reduce API cost. + + * Use `ApproximateNumberOfGroupsWithInflightMessages` in FIFO queues to diagnose throughput limits. + + * Review [SQS quotas](./sqs-quotas.html) to understand metric thresholds and service limits. + + +