Amazon Simple Notification Service
Developer Guide

Viewing Amazon CloudWatch Metrics and Logs for SMS Deliveries

You can use Amazon CloudWatch and Amazon CloudWatch Logs to monitor your SMS message deliveries.

Viewing Amazon CloudWatch Metrics

Amazon SNS automatically collects metrics about your SMS message deliveries and pushes them to Amazon CloudWatch. You can use CloudWatch to monitor these metrics and create alarms to alert you when a metric crosses a threshold. For example, you can monitor CloudWatch metrics to learn your SMS delivery rate and your month-to-date SMS charges.

For information about monitoring CloudWatch metrics, setting CloudWatch alarms, and the types of metrics available, see Monitoring Amazon SNS Topics Using CloudWatch.

Viewing CloudWatch Logs

You can collect information about successful and unsuccessful SMS message deliveries by enabling Amazon SNS to write to Amazon CloudWatch Logs. For each SMS message that you send, Amazon SNS will write a log that includes the message price, the success or failure status, the reason for failure (if the message failed), the message dwell time, and other information.

To enable CloudWatch Logs for your SMS messages

  1. Sign in to the Amazon SNS console.

  2. In the console menu, set the region selector to a region that supports SMS messaging.

  3. On the navigation panel, choose Text messaging (SMS).

  4. On the Text messaging (SMS) page, in the Text messaging preferences section, choose Edit.

  5. On the Edit text messaging preferences page, in the Delivery status logging section, do the following:

    1. For Success sample rate, specify the percentage of successful SMS deliveries for which Amazon SNS will write logs in CloudWatch Logs. For example:

      • To write logs only for failed deliveries, set this value to 0.

      • To write logs for 10% of your successful deliveries, set it to 10.

      If you don't specify a percentage, Amazon SNS writes logs for all successful deliveries.

    2. Choose Create new service role.

    3. Choose Create new roles.

    4. On the SNS is requesting permission to use resources in your account page, choose Allow.

  6. Choose Save changes.

Example Log for Successful SMS Delivery

The delivery status log for a successful SMS delivery will resemble the following example:

{ "notification": { "messageId": "34d9b400-c6dd-5444-820d-fbeb0f1f54cf", "timestamp": "2016-06-28 00:40:34.558" }, "delivery": { "phoneCarrier": "My Phone Carrier", "mnc": 270, "destination": "+1XXX5550100", "priceInUSD": 0.00645, "smsType": "Transactional", "mcc": 310, "providerResponse": "Message has been accepted by phone carrier", "dwellTimeMs": 599, "dwellTimeMsUntilDeviceAck": 1344 }, "status": "SUCCESS" }

Example Log for Failed SMS Delivery

The delivery status log for a failed SMS delivery will resemble the following example:

{ "notification": { "messageId": "1077257a-92f3-5ca3-bc97-6a915b310625", "timestamp": "2016-06-28 00:40:34.559" }, "delivery": { "mnc": 0, "destination": "+1XXX5550100", "priceInUSD": 0.00645, "smsType": "Transactional", "mcc": 0, "providerResponse": "Unknown error attempting to reach phone", "dwellTimeMs": 1420, "dwellTimeMsUntilDeviceAck": 1692 }, "status": "FAILURE" }

SMS Delivery Failure Reasons

The reason for a failure is provided with the providerResponse attribute. SMS messages might fail to deliver for the following reasons:

  • Blocked as spam by phone carrier

  • Destination is blacklisted

  • Invalid phone number

  • Message body is invalid

  • Phone carrier has blocked this message

  • Phone carrier is currently unreachable/unavailable

  • Phone has blocked SMS

  • Phone is blacklisted

  • Phone is currently unreachable/unavailable

  • Phone number is opted out

  • This delivery would exceed max price

  • Unknown error attempting to reach phone