> ## Documentation Index
> Fetch the complete documentation index at: https://opensre.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# AWS SQS

> Inspect SQS queue state — backlog depth, stuck consumers, and dead-letter wiring — during incidents

OpenSRE uses AWS SQS queue attributes to answer the first question of every queue-backed incident: **"what state is this queue actually in?"** When a queue alert fires, the planner can read message depth, in-flight count, visibility timeout, and dead-letter queue wiring — the signals that distinguish a normal backlog from consumers that are stuck.

Queue inspection is read-only and routed through the shared `aws_sdk_client` allowlist, so the integration cannot send, consume, or delete messages.

## Why this exists

Queue state lives in queue *attributes*, not in logs or metrics. A consumer that hangs without raising an exception writes no error line anywhere — so log search comes back clean while the queue quietly stops draining.

The specific failure this surfaces: a message that causes a consumer to hang past its `VisibilityTimeout` becomes visible again and is redelivered to the next consumer, which also hangs. Every consumer ends up holding the same message. Nothing errors, so nothing reaches the logs, and without a `RedrivePolicy` there is no receive-count ceiling to break the cycle. Reading two attributes — `in_flight_count` pinned at the consumer count and `has_dlq: false` — identifies it immediately.

## Prerequisites

* AWS credentials configured per the [AWS integration](https://opensre.com/docs/integrations/cloud/aws.md) (role ARN recommended) — SQS reuses the same account credentials and region, so no extra setup is needed
* IAM permissions for the two read-only SQS actions listed below

## How it works

SQS inspection is account-wide, so the tool becomes available to the planner whenever the [AWS integration](https://opensre.com/docs/integrations/cloud/aws.md) is configured — there is nothing queue-specific to set up. The region comes from the AWS integration (or `AWS_REGION`, defaulting to `us-east-1`).

The tool calls `ListQueues` to discover queues, then `GetQueueAttributes` for each one, so a prefix filter and a queue cap keep the fan-out bounded.

## Tools

| Tool | AWS API calls | What it returns |
| - | - | - |
| `get_sqs_queue_attributes` | `sqs:ListQueues`, `sqs:GetQueueAttributes` | Per-queue state — visible depth, in-flight count, visibility timeout, DLQ wiring, and FIFO flag. |

### Parameters

| Parameter | Default | Description |
| - | - | - |
| `queue_name_prefix` | — | Only inspect queues whose name starts with this prefix (e.g. `payments-`). Omit to inspect every queue. |
| `max_queues` | `20` | Maximum queues to inspect (1–100). Bounds the per-queue attribute fan-out. |
| `region` | `us-east-1` | AWS region to query. |

### Output fields

| Field | Meaning |
| - | - |
| `visible_count` | Messages available for delivery (`ApproximateNumberOfMessages`). |
| `in_flight_count` | Messages delivered but not yet deleted (`ApproximateNumberOfMessagesNotVisible`). |
| `visibility_timeout_seconds` | How long a message stays hidden after delivery before redelivery. |
| `has_dlq` / `redrive_policy` | Whether a dead-letter queue is configured, and its target plus `maxReceiveCount`. |
| `is_fifo` | Whether the queue is FIFO. |

### Reading the output

| Signal | Normal backlog | Stuck consumers |
| - | - | - |
| `visible_count` | High — producers outpacing consumers | Near zero |
| `in_flight_count` | Low | Pinned at the consumer/pod count |
| `has_dlq` | Usually `true` | Often `false` — nothing breaks the redelivery cycle |

> [!NOTE]
>
> A **missing** numeric attribute is reported as `null`, not `0`. An absent measurement and a genuinely empty queue are different findings, and collapsing them would let a metrics gap read as "the queue is drained".

> [!NOTE]
>
> Attributes prefixed `Approximate` are eventually consistent and can lag by around a minute. The field names keep the `approximate` semantics in mind — use them for shape and direction, not for exact reconciliation.

> [!NOTE]
>
> If one queue's attributes cannot be read (for example a per-queue policy denying `GetQueueAttributes`), that queue is returned with an `attributes_error` field and the remaining queues are still inspected — a single unreadable queue never sinks the whole investigation.

## IAM permissions

```json theme={null}
{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Effect": "Allow",
      "Action": [
        "sqs:ListQueues",
        "sqs:GetQueueAttributes"
      ],
      "Resource": "*"
    }
  ]
}
```

Attach this policy to the same IAM role or user already configured for the [AWS integration](https://opensre.com/docs/integrations/cloud/aws.md). If you are already using the AWS managed `ReadOnlyAccess` policy, both actions are already covered.

> [!NOTE]
>
> **Execution identity:** the AWS integration's `role_arn` / credentials gate *availability* and supply the region, but the calls themselves run through boto3's standard credential chain (environment variables, shared config, or the host's instance role) — the configured role is **not** assumed for the call. Ensure the identity the OpenSRE process runs as can perform these actions. This matches the other AWS tools (RDS/EKS/CloudTrail).

## Troubleshooting

| Symptom | Fix |
| - | - |
| **AccessDenied on `sqs:ListQueues`** | Add the IAM policy above to the role or user used by the AWS integration. |
| **No queues returned** | Check the prefix filter and confirm you are querying the region the queues live in. `ListQueues` is region-scoped. |
| **A queue shows `attributes_error`** | That queue's resource policy likely denies `sqs:GetQueueAttributes`. Other queues are unaffected. |
| **Fewer queues than expected** | The `max_queues` cap was hit; the response sets `truncated: true`. Raise `max_queues` (up to 100) or narrow with `queue_name_prefix`. |
| **Tool reports the wrong region** | Set `AWS_REGION`, or check the `region` field on the configured AWS integration. |


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.