Setup

Getting Started with AWS X-Ray

To get started with AWS X-Ray, launch a sample app in Elastic Beanstalk that is already instrumented to generate trace data. In a few minutes, you can launch the sample app, generate traffic, send segments to X-Ray, and view a service graph and traces in the AWS Management Console.

This tutorial uses a sample Java application to generate segments and send them to X-Ray. The application uses the Spring framework to implement a JSON web API and the AWS SDK for Java to persist data to Amazon DynamoDB. A servlet filter in the application instruments all incoming requests served by the application, and a request handler on the AWS SDK client instruments downstream calls to DynamoDB.

\[Scorekeep sample application flow\]

You use the X-Ray console to view the connections among client, server, and DynamoDB in a service map. The service map is a visual representation of the services that make up your web application, generated from the trace data that it generates by serving requests.

\[Viewing the connections among client, server, and DynamoDB in a service map\]

With the X-Ray SDK for Java, you can trace all of your application’s primary and downstream AWS resources by making two configuration changes: + Add the X-Ray SDK for Java’s tracing filter to your servlet configuration in a WebConfig class or web.xml file. + Take the X-Ray SDK for Java’s submodules as build dependencies in your Maven or Gradle build configuration.

You can also access the raw service map and trace data by using the AWS CLI to call the X-Ray API. The service map and trace data are JSON that you can query to ensure that your application is sending data, or to check specific fields as part of your test automation.

Topics + Prerequisites + Deploy to Elastic Beanstalk and Generate Trace Data + View the Service Map in the X-Ray Console + Configuration Amazon SNS Notifications + Explore the Sample Application + Clean Up + Next Steps

Prerequisites

This tutorial uses Elastic Beanstalk to create and configure the resources that run the sample application and X-Ray daemon. If you use an IAM user with limited permissions, add the Elastic Beanstalk managed user policy to grant your IAM user permission to use Elastic Beanstalk, and the AWSXrayReadOnlyAccess managed policy for permission to read the service map and traces in the X-Ray console.

Create an Elastic Beanstalk environment for the sample application. If you haven’t used Elastic Beanstalk before, this will also create a service role and instance profile for your application.

To create an Elastic Beanstalk environment

  1. Open the Elastic Beanstalk Management Console with this preconfigured link: https://console.aws.amazon.com/elasticbeanstalk/#/newApplication?applicationName=scorekeep&solutionStackName=Java

  2. Choose Create application to create an application with an environment running the Java 8 SE platform.

  3. When your environment is ready, the console redirects you to the environment Dashboard.

  4. Click the URL at the top of the page to open the site.

The instances in your environment need permission to send data to the AWS X-Ray service. Additionally, the sample application uses Amazon S3 and DynamoDB. Modify the default Elastic Beanstalk instance profile to include permissions to use these services.

To add X-Ray, Amazon S3 and DynamoDB permissions to your Elastic Beanstalk environment

  1. Open the Elastic Beanstalk instance profile in the IAM console: aws-elasticbeanstalk-ec2-role.

  2. Choose Attach Policy.

  3. Attach AWSXrayFullAccess, AmazonS3FullAccess, and AmazonDynamoDBFullAccess to the role.

Deploy to Elastic Beanstalk and Generate Trace Data

Deploy the sample application to your Elastic Beanstalk environment. The sample application uses Elastic Beanstalk configuration files to configure the environment for use with X-Ray and create the DynamoDB that it uses automatically.

To deploy the source code

  1. Download the sample app: eb-java-scorekeep-xray-gettingstarted-v1.3.zip

  2. Open the Elastic Beanstalk console.

  3. Navigate to the management console for your environment.

  4. Choose Upload and Deploy.

  5. Upload eb-java-scorekeep-xray-gettingstarted-v1.3.zip, and then choose Deploy.

The sample application includes a front-end web app. Use the web app to generate traffic to the API and send trace data to X-Ray.

To generate trace data

  1. In the environment Dashboard, click the URL to open the web app.

  2. Choose Create to create a user and session.

  3. Type a game name, set the Rules to Tic Tac Toe, and then choose Create to create a game.

  4. Choose Play to start the game.

  5. Choose a tile to make a move and change the game state.

Each of these steps generates HTTP requests to the API, and downstream calls to DynamoDB to read and write user, session, game, move, and state data.

View the Service Map in the X-Ray Console

You can see the service map and traces generated by the sample application in the X-Ray console.

To use the X-Ray console

  1. Open the service map page of the X-Ray console.

  2. The console shows a representation of the service graph that X-Ray generates from the trace data sent by the application.
    \[Representation of service graph X-Ray generates from trace data sent by the application\]

The service map shows the web app client, the API running in Elastic Beanstalk, the DynamoDB service, and each DynamoDB table that the application uses. Every request to the application, up to a configurable maximum number of requests per second, is traced as it hits the API, generates requests to downstream services, and completes.

You can choose any node in the service graph to view traces for requests that generated traffic to that node. Currently, the Amazon SNS node is red. Drill down to find out why.

To find the cause of the error

  1. Choose the node named SNS.

  2. Choose the trace from the Trace list. This trace doesn’t have a method or URL because it was recorded during startup instead of in response to an incoming request.
    \[Choosing a trace from the Trace list\]

  3. Choose the red status icon to open the Exceptions page for the SNS subsegment.
    \[Choosing the red status icon opens the Exceptions page for the SNS subsegment\]

  4. The X-Ray SDK automatically captures exceptions thrown by instrumented AWS SDK clients and records the stack trace.
    \[Exceptions tab showing captured exceptions and recorded stack trace\]

The cause indicates that the email address provided in a call to createSubscription made in the WebConfig class was invalid. Let’s fix that.

Configuration Amazon SNS Notifications

Scorekeep uses Amazon SNS to send notifications when users complete a game. When the application starts up, it tries to create a subscription for an email address defined in an environment variable. That call is currently failing, causing the Amazon SNS node in your service map to be red. Configure a notification email in an environment variable to enable notifications and make the service map green.

To configure Amazon SNS notifications for Scorekeep

  1. Open the Elastic Beanstalk console.

  2. Navigate to the management console for your environment.

  3. Choose Configuration.

  4. Choose Software Configuration.

  5. Under Environment Properties, replace the default value with your email address.
    \[Setting environment properties\] Note
    The default value uses an AWS CloudFormation function to retrieve a parameter stored in a configuration file (a dummy value in this case).

  6. Choose Apply.

When the update completes, Scorekeep restarts and creates a subscription to the SNS topic. Check your email and confirm the subscription to see updates when you complete a game.

\[Service map after updates\]