Setup Guide

Quick Start

1. Create an account — Sign up with your email. We'll send a magic link (no password needed).
2. Connect AWS — Go to Settings and add your AWS account using access keys or an IAM role.
3. Discover queues — DeadQueue auto-discovers all SQS dead letter queues in the connected region.
4. Set up alerts — Go to Alerts and add Slack, email, or PagerDuty channels.
5. Monitor — Your dashboard shows queue depth, message age, and trend charts. Alerts fire automatically on status changes.

1. Connect Your AWS Account

DeadQueue supports two ways to connect your AWS account:

Option A: Access Keys (default)

1. In the AWS Console, go to IAM → Users → Create user.
2. Name it something like deadqueue-monitor.
3. Attach the permissions listed in the IAM Permissions section below.
4. Go to the user's Security credentials tab and create an access key.
5. In DeadQueue, go to Settings, select Access Keys, and paste the Access Key ID and Secret Access Key.
6. Select your AWS region and click Connect Account.

Your credentials are encrypted at rest using AES-256-GCM. They are never logged or exposed via the API.

Option B: IAM Role (cross-account)

1. In the AWS Console, go to IAM → Roles → Create role.
2. Select Another AWS account as the trusted entity.
3. Enter the DeadQueue AWS account ID (provided in the Settings page) and enable Require external ID.
4. Attach the permissions listed in the IAM Permissions section below.
5. In DeadQueue, go to Settings, select IAM Role, and paste the Role ARN.
6. Select your AWS region and click Connect Account.

IAM Role auth uses temporary credentials via STS AssumeRole. No long-lived secrets are stored.

2. IAM Permissions

DeadQueue needs read-only access to SQS and minimal STS permissions. Create a policy with the following JSON:

{
    "Version": "2012-10-17",
    "Statement": [
        {
            "Sid": "DeadQueueMonitoring",
            "Effect": "Allow",
            "Action": [
                "sqs:GetQueueAttributes",
                "sqs:ListQueues",
                "sqs:ListDeadLetterSourceQueues",
                "sqs:GetQueueUrl"
            ],
            "Resource": "*"
        },
        {
            "Sid": "DeadQueueReplay",
            "Effect": "Allow",
            "Action": [
                "sqs:StartMessageMoveTask",
                "sqs:ListMessageMoveTasks",
                "sqs:CancelMessageMoveTask"
            ],
            "Resource": "*"
        },
        {
            "Sid": "DeadQueueIdentity",
            "Effect": "Allow",
            "Action": "sts:GetCallerIdentity",
            "Resource": "*"
        }
    ]
}

If you don't need message replay, you can omit the DeadQueueReplay statement. The monitoring-only permissions are completely read-only.

3. Queue Discovery

After connecting your AWS account, DeadQueue automatically discovers all SQS queues in the selected region that are configured as dead letter queues (i.e., they are the target of another queue's redrive policy).

For each discovered DLQ, DeadQueue tracks:

• Depth — The approximate number of messages currently in the queue.
• Oldest message age — How long the oldest message has been sitting in the DLQ (in seconds).
• Status — OK (empty), WARNING (depth ≥ threshold), or CRITICAL (depth ≥ 10x threshold).
• Source queue — The queue that routes failed messages to this DLQ.

Queues are polled every 60 seconds. The dashboard and trend charts update automatically.

4. Configure Alerts

DeadQueue fires alerts when a queue's status changes (e.g., OK → WARNING, WARNING → CRITICAL, or any state → RESOLVED). Alerts are sent to all enabled channels.

Supported channels

• Slack — Provide an Incoming Webhook URL. Alerts are sent as rich Block Kit messages with queue name, depth, age, status, and runbook link.
• Email — Provide an email address. Alerts are sent as HTML emails via Resend.
• PagerDuty — Provide a routing key from a PagerDuty service integration. Alerts use the Events API v2 with automatic deduplication (resolved alerts auto-resolve the PagerDuty incident).

Setting up Slack

1. In Slack, go to your workspace's App Directory and search for Incoming Webhooks.
2. Add a new webhook and select the channel where you want alerts (e.g., #ops-alerts).
3. Copy the webhook URL (starts with https://hooks.slack.com/).
4. In DeadQueue, go to Alerts, select Slack Webhook, paste the URL, and click Add Channel.

→ Full Slack setup walkthrough — step-by-step with screenshots, testing instructions, and troubleshooting.

Setting up PagerDuty

1. In PagerDuty, go to Services and select (or create) a service.
2. Under Integrations, add a new integration using Events API v2.
3. Copy the Integration Key (routing key).
4. In DeadQueue, go to Alerts, select PagerDuty, paste the routing key, and click Add Channel.

5. Runbooks & Notes

Each queue supports a runbook URL and custom notes. These are included in every alert so the on-call engineer knows exactly where to start.

1. From the Dashboard, click on a queue to open the detail view.
2. Scroll down to the Queue Settings section.
3. Add a Runbook URL (e.g., a link to your Confluence page, Notion doc, or GitHub wiki).
4. Add Notes (e.g., "This queue processes Stripe webhooks — check payment service first").
5. Optionally adjust the Depth threshold (default: 1) and toggle monitoring on/off.
6. Click Save Settings.

Tip: A good runbook answers "what broke, what do I check first, and who do I escalate to" in under 30 seconds.

6. Message Replay

DeadQueue lets you redrive messages from a DLQ back to its source queue for reprocessing, using the native AWS StartMessageMoveTask API.

1. From the Dashboard, click on a queue that has messages (depth > 0).
2. In the Message Replay section, click Start Replay.
3. Messages are moved back to the source queue by AWS. Progress is tracked in the replay history table.
4. You can cancel an in-progress replay if needed.

Replay requires the sqs:StartMessageMoveTask, sqs:ListMessageMoveTasks, and sqs:CancelMessageMoveTask permissions. See IAM Permissions.

FAQ