| name | sns-advanced-diagnostics |
| version | 1.0.0 |
| last_updated | 2025-04-12 |
| description | Use this skill to investigate and troubleshoot advanced Amazon SNS problems by analyzing delivery failures, SMS sending, mobile push notifications, subscription filtering, FIFO topics, cross-account access, and DLQ configurations using structured runbooks. Activate when: delivery failures, delivery status logging issues, DLQ configuration, SMS sending failures, spending limits, origination numbers, platform application issues, push notification failures, subscription filter policies, attribute-based filtering, FIFO topic issues, deduplication problems, cross-account subscriptions, access policy issues, or the user says something is wrong with SNS without naming specific symptoms.
|
| compatibility | Requires AWS CLI or SDK access with SNS, SQS, Lambda, CloudWatch, CloudTrail, IAM, and optionally Pinpoint permissions.
|
SNS Advanced Diagnostics
When to use
Any advanced Amazon SNS investigation where the console alone is insufficient — delivery failure analysis, SMS troubleshooting, mobile push debugging, filter policy configuration, FIFO topic issues, cross-account access, or DLQ management.
Investigation workflow
Step 1 — Collect and triage
aws sns list-topics
aws sns get-topic-attributes --topic-arn <topic-arn>
aws sns list-subscriptions-by-topic --topic-arn <topic-arn>
aws cloudwatch get-metric-statistics --namespace AWS/SNS --metric-name NumberOfMessagesPublished --dimensions Name=TopicName,Value=<topic-name> --start-time <start> --end-time <end> --period 3600 --statistics Sum
aws cloudwatch get-metric-statistics --namespace AWS/SNS --metric-name NumberOfNotificationsFailed --dimensions Name=TopicName,Value=<topic-name> --start-time <start> --end-time <end> --period 3600 --statistics Sum
Step 2 — Domain deep dive
aws sns get-subscription-attributes --subscription-arn <sub-arn>
aws sns get-sms-attributes
aws sns list-platform-applications
aws sns get-platform-application-attributes --platform-application-arn <app-arn>
aws sns check-if-phone-number-is-opted-out --phone-number <number>
aws sqs get-queue-attributes --queue-url <dlq-url> --attribute-names ApproximateNumberOfMessages
Step 3 — Detailed investigation
aws logs filter-log-events --log-group-name sns/<region>/<account-id>/<topic-name> --start-time <epoch-ms> --end-time <epoch-ms>
aws cloudtrail lookup-events --lookup-attributes AttributeKey=EventSource,AttributeValue=sns.amazonaws.com --max-results 10
aws sns list-phone-numbers-opted-out
aws sns list-origination-numbers
Read references/guardrails.md before concluding on any SNS issue.
Tool quick reference
| Tool / API | When to use |
|---|
get-topic-attributes | Topic configuration and policy |
get-subscription-attributes | Subscription details and filter |
get-sms-attributes | SMS sending configuration |
list-platform-applications | Mobile push platforms |
check-if-phone-number-is-opted-out | SMS opt-out status |
list-origination-numbers | SMS origination numbers |
get-data-protection-policy | Data protection settings |
cloudwatch get-metric-statistics | Delivery metrics |
logs filter-log-events | Delivery status logs |
Gotchas: SNS
- Delivery status logging must be explicitly enabled per protocol (HTTP, Lambda, SQS, SMS, Application). It is NOT on by default.
- SMS spending limit: AWS accounts start in the SMS sandbox with a $1.00 monthly limit. Production access requires a spending limit increase request.
- SMS opt-out: Recipients can opt out by replying STOP. Opted-out numbers silently fail delivery. Check opt-out list before diagnosing SMS failures.
- Filter policies: By default, filter policies match against message attributes. MessageBody-based filtering requires setting FilterPolicyScope to MessageBody.
- FIFO topics: Require .fifo suffix. Messages are delivered in order within a message group. Deduplication uses MessageDeduplicationId or content-based deduplication.
- Cross-account: Topic policy must explicitly allow the other account to subscribe or publish. The subscription must be confirmed by the endpoint owner.
- DLQ: Dead-letter queues for SNS are configured per subscription, not per topic. The DLQ must be an SQS queue in the same Region.
- Mobile push: Platform applications require platform-specific credentials (APNs certificate/key for iOS, FCM API key for Android).
- Message size: Standard topics support up to 256 KB. FIFO topics also support 256 KB. For larger payloads, use S3 with a reference in the message.
- Retry policy: SNS has built-in retry policies per protocol. HTTP/S retries for up to 23 days with exponential backoff. Lambda retries 3 times. SQS has no retries (immediate delivery).
Anti-hallucination rules
- Always check delivery status logs before concluding on delivery failures — they contain the specific error.
- SMS sandbox limits sending to verified numbers only — do not assume production SMS access.
- Filter policies match message attributes by default, NOT message body — verify FilterPolicyScope.
- FIFO topics require .fifo suffix — standard topics cannot be converted to FIFO.
- DLQs are per-subscription, not per-topic — each subscription needs its own DLQ configuration.
- Spend no more than 2 minutes on any single hypothesis. Pivot if inconclusive.
20 runbooks
| Category | IDs | Covers |
|---|
| A — Delivery | A1-A3 | Delivery failures, delivery status logging, DLQ |
| B — SMS | B1-B3 | SMS sending failures, spending limits, origination numbers |
| C — Mobile Push | C1-C2 | Platform application, push notification failures |
| D — Filtering | D1-D2 | Subscription filter policies, attribute-based |
| E — FIFO | E1-E2 | FIFO topics, deduplication |
| F — Cross-Account | F1-F2 | Cross-account subscriptions, access policy |
| Z — Catch-All | Z1 | General troubleshooting |
