Active tracing in Amazon SNS

You can use AWS X-Ray to trace and analyze user requests as they travel through your Amazon SNS topics to your Amazon Data Firehose, AWS Lambda, Amazon SQS, and HTTP/S endpoint subscriptions. Because X-Ray gives you an end-to-end view of an entire request, you can view what is calling your Amazon SNS topic, and what is downstream of your topic's subscriptions. You can analyze latencies in your messages and their backend services (for example, how long a request spends in a topic, and how long it took to deliver the message to each of the topic’s subscriptions).

Important

Amazon SNS topics with numerous subscriptions may reach a size limit and not be fully traced. For information about trace document size limits, see X-ray service quotas in AWS General Reference.

If you call an Amazon SNS API from a service that's already being traced, Amazon SNS passes the trace through, even if X-Ray tracing isn't enabled on the API.

Amazon SNS supports X-Ray tracing for both standard and FIFO topics. You can enable X-Ray for an Amazon SNS topic by using the Amazon SNS console, Amazon SNS SetTopicAttributes API, Amazon Simple Notification Service CLI Reference, or AWS CloudFormation.

To learn more about using Amazon SNS with X-Ray, see Amazon SNS and AWS X-Ray in the AWS X-Ray Developer Guide.

Active tracing permissions

When using the Amazon SNS console, Amazon SNS attempts to create the necessary permissions for the Amazon SNS topic to call X-Ray. The attempt can be rejected if you don't have sufficient permissions to use the Amazon SNS console. For more information, see Identity and access management in Amazon SNS and Example cases for Amazon SNS access control.

When using the CLI, you must manually configure the permissions. Those permissions are configured using resource policies. For more on using required permissions in X-Ray, see Amazon SNS and AWS X-Ray.

Enabling active tracing on an Amazon SNS topic (console)

When active tracing is enabled on an Amazon SNS topic, it reads the trace ID, sends the data to the customer based on the trace ID, and propagates the trace ID to downstream services.

1. Sign in to the Amazon SNS console.

2. Choose a topic or create a new one. For more details on creating topics, see Creating an Amazon SNS topic.

3. On the Create topic page, in the Details section, choose a topic type: FIFO or Standard.

   1. Enter a Name for the topic.

   2. (Optional) Enter a Display name for the topic.

4. Expand Active tracing, and choose Use active tracing.

Once you've enabled X-Ray for your Amazon SNS topic, you can use the X-Ray service map to view the end-to-end traces and service maps for the topic.

Enabling active tracing on an Amazon SNS topic (AWS SDK)

The following code example shows how to enable active tracing on an Amazon SNS topic by using the AWS SDK for Java.

public static void enableActiveTracing(SnsClient snsClient, String topicArn) {

        try {

            SetTopicAttributesRequest request = SetTopicAttributesRequest.builder()
                .attributeName("TracingConfig")
                .attributeValue("Active")
                .topicArn(topicArn)
                .build();

            SetTopicAttributesResponse result = snsClient.setTopicAttributes(request);
            System.out.println("\n\nStatus was " + result.sdkHttpResponse().statusCode() + "\n\nTopic " + request.topicArn()
                + " updated " + request.attributeName() + " to " + request.attributeValue());

        } catch (SnsException e) {
            System.err.println(e.awsErrorDetails().errorMessage());
        }
    }

Enabling active tracing on an Amazon SNS topic (AWS CLI)

The following code example shows how to enable active tracing on an Amazon SNS topic by using the AWS CLI.

aws sns set-topic-attributes \
    --topic-arn arn:aws:sns:us-west-2:123456789012:MyTopic \
    --attribute-name TracingConfig \
    --attribute-value Active

Enabling active tracing on an Amazon SNS topic (AWS CloudFormation)

The following AWS CloudFormation stack shows how to enable active tracing on an Amazon SNS topic.

AWSTemplateFormatVersion: 2010-09-09
Resources:
  MyTopicResource:
    Type: 'AWS::SNS::Topic'
    Properties:
      TopicName: 'MyTopic'
      TracingConfig: 'Active'

Verifying active tracing is enabled for your topic

You can use the Amazon SNS console to verify if active tracing is enabled for your topic, or when the resource policy has failed to be added.

1. Sign in to the Amazon SNS console.

2. In the left navigation pane, choose Topics.

3. On the Topics page, select a topic.

4. Choose the Integrations tab.

   When active tracing is enabled, a green Active icon is displayed.

5. If you have enabled active tracing and you don't see that the resource policy has been added, choose Create policy to add the additional required permissions.

Testing active tracing

1. Sign in to the Amazon SNS console.

2. Create an Amazon SNS topic. For details on how to do this, see To create a topic using the AWS Management Console.

3. Expand Active tracing, and choose Use active tracing.

4. Publish a message to the Amazon SNS topic. For details on how to do this, see To publish messages to Amazon SNS topics using the AWS Management Console.

5. Use the X-Ray service map to view the end-to-end traces and service maps for the topic.