> ## 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](/docs/aws) (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](/docs/aws) 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>

<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>

<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.
</Note>

## 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](/docs/aws). 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).
</Note>

## 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.                                                      |