Services or capabilities described in Amazon Web Services documentation might vary by Region. To see the differences applicable to the China Regions, see Getting Started with Amazon Web Services in China (PDF).

Active tracing in Amazon SNS

Use Amazon X-Ray to trace and analyze user requests as they pass through your Amazon SNS topics to Amazon Data Firehose, Amazon Lambda, Amazon SQS, and HTTP/S endpoint subscriptions.

With X-Ray, you get an end-to-end view of each request, allowing you to:

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 Amazon CloudFormation.

To learn more about using Amazon SNS with X-Ray, see Amazon SNS and Amazon X-Ray in the Amazon 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 Amazon X-Ray.

Enabling active tracing on an Amazon SNS topic using the Amazon 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.

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 using the Amazon SDK

The following code example shows how to enable active tracing on an Amazon SNS topic by using the Amazon 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 using the Amazon CLI

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

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

Enabling active tracing on an Amazon SNS topic using Amazon CloudFormation

The following Amazon 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.

Testing active tracing