AWS X-Ray
Developer Guide

Amazon SNS and AWS X-Ray

AWS X-Ray integrates with Amazon Simple Notification Service (Amazon SNS) to trace messages that are passed through Amazon SNS. If an Amazon SNS publisher traces its client with the X-Ray SDK, subscribers can retrieve the tracing header and continue to propagate the original trace from the publisher with the same trace ID. This continuity enables users to trace, analyze, and debug throughout downstream services.

Amazon SNS trace context propagation currently supports the following subscribers:

  • HTTP/HTTPS – For HTTP/HTTPS subscribers, you can use the X-Ray SDK to trace the incoming message request. For more information and examples in Java, see Tracing Incoming Requests with the X-Ray SDK for Java.

  • AWS Lambda – For Lambda subscribers with active tracing enabled, Lambda records a segment with details about the function invocation, and sends it to the publisher's trace. For more information, see AWS Lambda and AWS X-Ray.

Use the following instructions to learn how to create a basic context between X-Ray and Amazon SNS using a Lambda subscriber. You will create two Lambda functions and an Amazon SNS topic. Then, in the X-Ray console, you can view the trace ID propagated throughout their interactions.

Requirements

Creating a Lambda Subscriber Function

In the following steps, the sample Lambda function MessageSubscriber is implemented in Node.js and is subscribed as an endpoint to an Amazon SNS topic. The MessageSubscriber function creates a custom process_message subsegment with the AWSXRay.captureFunc command. The function writes a simple message as an annotation to the subsegment.

To create the subscriber package

  1. Create a file folder and name it to indicate it's the subscriber function (for example, sns-xray-subscriber).

  2. Create two files: index.js and package.json.

  3. Paste the following code into index.js.

    var AWSXRay = require('aws-xray-sdk'); exports.handler = function(event, context, callback) { AWSXRay.captureFunc('process_message', function(subsegment) { var message = event.Records[0].Sns.Message; subsegment.addAnnotation('message_content', message); subsegment.close(); }); callback(null, "Message received."); };
  4. Paste the following code into package.json.

    { "name": "sns-xray-subscriber", "version": "1.0.0", "description": "A demo service to test SNS X-Ray trace header propagation", "dependencies": { "aws-xray-sdk": "^2.2.0" } }
  5. Run the following script within the sns-xray-subscriber folder. It creates a package-lock.json file and a node_modules folder, which handle all dependencies.

    npm install --production
  6. Compress the sns-xray-subscriber folder into a .zip file.

To create a subscriber function and enable X-Ray

  1. Open the Lambda console, and then choose Create a function.

  2. Choose Author from scratch:

    • For Function name, provide a name (for example, MessageSubscriber).

    • For Runtime, use Node.js 10.x.

  3. Choose Create function to create and display your function in the Lambda console.

  4. In Function code, under Code entry type, choose Upload a .zip file.

  5. Choose the subscriber package you created. To upload, choose Save in the upper right of the console.

  6. In Debugging and error handling, select the Enable AWS X-Ray box.

  7. Choose Save.

Creating an Amazon SNS Topic

When Amazon SNS receives requests, it propagates the trace header to its endpoint subscriber. In the following steps, you create a topic and then set the endpoint as the Lambda function you created earlier.

To create an Amazon SNS topic and subscribe a Lambda function

  1. Open the SNS console.

  2. Choose Topics, and then choose Create topic. For Name, provide a name.

  3. In Subscriptions, choose Create subscription.

  4. Record the topic ARN (for example, arn:aws:sns:{region}:{account id}:{topic name}).

  5. Choose Create subscription:

    • For Protocol, choose AWS Lambda.

    • For Endpoint, choose the ARN of the receiver Lambda function you created from the list of available Lambda functions.

  6. Choose Create subscription.

Creating a Lambda Publisher Function

In the following steps, the sample Lambda function MessagePublisher is implemented in Node.js. The function sends a message to the Amazon SNS topic you created earlier. The function uses the AWS SDK for JavaScript to send notifications from Amazon SNS, and the X-Ray SDK for Node.js to instrument the AWS SDK client.

To create the publisher package

  1. Create a file folder and name it to indicate it's the publisher function (for example, sns-xray-publisher).

  2. Create two files: index.js and package.json.

  3. Paste the following code into index.js.

    var AWSXRay = require('aws-xray-sdk'); var AWS = AWSXRay.captureAWS(require('aws-sdk')); exports.handler = function(event, context, callback) { var sns = new AWS.SNS(); sns.publish({ // You can replace the following line with your custom message. Message: process.env.MESSAGE || "Testing X-Ray trace header propagation", TopicArn: process.env.TOPIC_ARN }, function(err, data) { if (err) { console.log(err.stack); callback(err); } else { callback(null, "Message sent."); } }); };
  4. Paste the following code into package.json.

    { "name": "sns-xray-publisher", "version": "1.0.0", "description": "A demo service to test SNS X-Ray trace header propagation", "dependencies": { "aws-xray-sdk": "^2.2.0" } }
  5. Run the following script within the sns-xray-publisher folder. It creates a package-lock.json file and a node_modules folder, which handle all dependencies.

    npm install --production
  6. Compress the sns-xray-publisher folder into a .zip file.

To create a publisher function and enable X-Ray

  1. Open the Lambda console, and then choose Create function.

  2. Choose Author from scratch:

    • For Name, provide a name (for example, MessagePublisher).

    • For Runtime, use Node.js 10.x.

  3. In Permissions, expand Choose or create an execution role:

    • For Execution role, choose Create a new role from AWS policy templates.

    • For Role name, provide a name.

    • For Policy templates, choose Amazon SNS publish policy.

  4. Choose Create function to create and display your function in the Lambda console.

  5. In Function code, under Code entry type, choose Upload a .zip file.

  6. Choose the publisher package that you created. To upload, choose Save in the upper right of the console.

  7. In Environment variables, add a variable:

    • For Key, use the key name TOPIC_ARN, which is defined in the publisher function.

    • For Value, use the Amazon SNS topic ARN you recorded previously.

  8. Optionally, add another variable:

    • For Key, provide a key name (for example, MESSAGE).

    • For Value, enter any custom message.

  9. In Debugging and error handling, select the Enable AWS X-Ray box.

  10. Choose Save.

Testing and Validating Context Propagation

Both publisher and subscriber functions enable Lambda active tracing when sending traces. The publisher function uses the X-Ray SDK to capture the SendMessage SQS API call. Then, Amazon SNS propagates the trace header to the subscriber. Finally, the subscriber picks up the trace header and continues the trace. Follow the trace ID in the following steps.

To create a publisher function and enable X-Ray

  1. Open the Lambda console, and then choose the publisher function that you created previously.

  2. Choose Test.

  3. Choose Create a new test event:

    • For Event template, choose the Hello World template.

    • For Event name, provide a name.

  4. Choose Create.

  5. Choose Test again.

  6. To verify, open the X-Ray console. Wait at least 10 seconds for the trace to appear.

  7. When the service map is generated, validate that your two Lambda functions and the Amazon SNS topic appear.

  8. Choose the MessageSubscriber segment, and then choose View traces.

  9. Choose the trace from the list to reach the Details page.

  10. Choose the process_message subsegment.

  11. Choose the Annotations tab to see the message_content key with the message value from the sender.