Using the Delivery Status feature of Amazon SNS

Today we released a new feature for Amazon SNS that enables developers to collect feedback on successful and unsuccessful delivery attempts of their messages to mobile push notification platforms (Apple (APNS), Google (GCM), Amazon (ADM), Windows (WNS and MPNS) and Baidu). It also provides other important information such as dwell times in Amazon SNS. This information is captured in an Amazon CloudWatch Log group that is created automatically by Amazon SNS when this feature is enabled via the Amazon SNS console or via the Amazon SNS APIs.

In this post, we will see how to enable the Delivery Status feature through the Amazon SNS console and the Amazon SNS APIs; followed by how to capture metrics via Amazon CloudWatch Metrics based on information generated by your application after this feature is activated.

Enabling the Delivery Status feature through the Amazon SNS console

Here is how you can set up this feature for your application via the Amazon SNS console:

Step 1: Navigate to the application that you want to enable this feature for. Then, from the Application Actions drop-down menu, choose the Delivery Status option.

Step 2: In the Delivery Status window, click the Create IAM Roles button.

After clicking the Create IAM Roles button, you should see the IAM page.

Step 3: On the IAM page, click the Allow button. This will allow Amazon SNS to gain write-access to Amazon CloudWatch Logs on your behalf.

After the IAM role assignment succeeds, you will see that the fields for IAM Role for Success Feedback and IAM Role for Failure Feedback are automatically filled with the ARN for the appropriate IAM role.

You can also choose the sampling rate for successful deliveries on this window. Successful deliveries can be sampled based on a percentage you define, whereas 100 percent of failed deliveries are logged to Amazon CloudWatch Logs. In this example, we will choose 100 percent for the sampling rate.

Save this configuration by clicking the Save Configuration button. This enables the Delivery Status feature for your application.

Enabling the Delivery Status feature via Amazon SNS APIs

You can also enable the Delivery Status feature for your application via the Amazon SNS APIs available via the AWS SDK. Here is an example in Java:

SetPlatformApplicationAttributesRequest spar = new SetPlatformApplicationAttributesRequest();
Map<String, String> attributes =new HashMap<String, String>();

attributes.put("SuccessFeedbackRoleArn",
               "arn:aws:iam::517641087674:role/logs");
attributes.put("FailureFeedbackRoleArn",
               "arn:aws:iam::517641087674:role/logs");
attributes.put("SuccessFeedbackSampleRate", "30");
spar.withAttributes(attributes);

spar.setPlatformApplicationArn("arn:aws:sns:us-east1:517641087674:app/APNS/myApp");
sns.setPlatformApplicationAttributes(spar);

In the above example, we indicate that the application (with ARN arn:aws:sns:us-east1:123456789000:app/APNS/myApp) wants this feature activated by setting application-level attributes in the SetPlatformApplicationAttributesRequest object and assigning it to the application via the setPlatformApplicationAttributes method. The attributes should include a SuccessFeedbackRoleArn, a FailureFeedbackRoleArn and a SuccessFeedbackSampleRate.

Once the feature is enabled, Amazon SNS will start logging successful and failed message delivery attempts. In order to view this information, you will need to navigate to Amazon CloudWatch Logs. Please note that, Amazon SNS follows a “lazy creation” policy for the Amazon CloudWatch Logs group. That is, it does not create the Amazon CloudWatch Logs group until the first successful or failed delivery attempt occurs after enabling the feature for the application. Therefore, we recommend publishing a few messages before proceeding to see how to capture information from these logs, and creating Amazon CloudWatch Metrics that can help you visualize events through graphs or generate alarms based on thresholds.

Capturing Metrics through Amazon CloudWatch

After you are done publishing a few messages in the application, here is how you would capture Amazon CloudWatch Metrics:

Step 1: Navigate to the Amazon CloudWatch console and click Logs to view the Logs section. You will see the log group created by Amazon SNS for the Delivery Status feature amongst other log groups that you may have.

Click on the log group to open it up. You should see one or more log streams that Amazon SNS writes to. Open any one of the log streams by clicking on it to see the individual log entries in that stream.

Here is an example of what you might see in the individual log entries

Step 2: The next activity that you perform is to create a metric to count the occurrences of a particular pattern in log entries. Metrics can then be used to graphs values or trigger alarms. To create a metric, you first need to define a metric filter. To define a metric filter, navigate back to the Logs page in the Amazon CloudWatch console, choose the log group created by Amazon SNS, and choose Create Metric Filter. Upon performing these actions; you should see the Define Logs Metric Filter page.

Because Amazon SNS writes data to the logs in a JSON format, you can create any filter for metrics using a JSON pattern like {.$.key.key.key=*} This will extract any value of interest from the logs. For example, if you use {$.delivery.statusCode=403} you will be able to retrieve events with a 403 return code. You can test the output of your filter on this page. Once your filter is defined, click Assign Metric to assign a value for each match that the filter generates.

Step 3: On clicking Assign Metric, you will be taken to the Create Metric Filter and Assign a Metric page. On this page, you can give your filter a name and assign your metric a name as well. In addition, you can choose to provide a constant metric value whenever the filter returns with a match or you can actually capture the value in the logs by specifying the JSON format. For example, if you wanted to count the actual dwell-time in Amazon SNS for each log entry, you would enter the Metric Value as $.delivery.dwellTimeMs

Once done, click Create Filter to create the filter. Now you will be able to count specific occurrences or values based on how you created the Amazon CloudWatch Metric and get a better understanding of what is happening to Amazon SNS delivery attempts for your messages.

We look forward to your feedback on this feature through the Amazon SNS forum and our Twitter account.