AWS SQS

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

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

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.

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

{
  "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. If you are already using the AWS managed ReadOnlyAccess policy, both actions are already covered.

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.

Overview

LLM providers

Observability and incidents

Cloud, code, and collaboration

Messaging

Data and workflow systems

Why this exists

Prerequisites

How it works

Tools

Parameters

Output fields

Reading the output

IAM permissions

Troubleshooting

​Why this exists

​Prerequisites

​How it works

​Tools

​Parameters

​Output fields

​Reading the output

​IAM permissions

​Troubleshooting

Why this exists

Prerequisites

How it works

Tools

Parameters

Output fields

Reading the output

IAM permissions

Troubleshooting