Menu
AWS X-Ray
Developer Guide

Using AWS X-Ray

Use the X-Ray SDK and AWS service integration to instrument requests to your applications running on Amazon EC2, Elastic Beanstalk, or Amazon ECS.

To instrument your application code, you can use the X-Ray SDK. The SDK records data about incoming and outgoing requests and sends it to the X-Ray daemon, which relays the data in batches to X-Ray. For example, when your application calls DynamoDB to retrieve user information from a DynamoDB table, the X-Ray SDK records data both the client request and the downstream call to DynamoDB.

Other AWS services make it easier to instrument your application's components by integrating with X-Ray. Service integration can include adding tracing headers to incoming requests, sending trace data to X-Ray, or running the X-Ray daemon. For example, Elastic Beanstalk platforms include the X-Ray daemon and run it for you.

Many instrumentation scenarios require only configuration changes. For example, you can instrument all incoming HTTP requests and downstream calls to AWS services that your Java application makes by adding the X-Ray SDK for Java's filter to your servlet configuration, and taking the AWS SDK Instrumentor submodule as a build dependency. For advanced instrumentation, you can modify your application code to customize and annotate the data that the SDK sends to X-Ray.

Supported Languages and Frameworks

AWS X-Ray provides tools and integration to support a variety of languages, frameworks and platforms.

Java

In any Java application, you can use the X-Ray SDK for Java classes to instrument incoming requests, AWS SDK clients, and outgoing HTTP calls. Automatic request instrumentation is available for frameworks that support Java servlets. Automatic SDK instrumentation is avialable through the AWS SDK Instrumentor submodule.

See The AWS X-Ray SDK for Java for more information.

  • Tomcat – Add a servlet filter to your deployment descriptor (web.xml) to instrument incoming requests.

  • Spring Boot – Add a servlet filter to your WebConfig class to instrument incoming requests.

  • Other frameworks – Add a servlet filter if your framework supports servlets, or manually create segments and make sampling decisions on incoming requests if it doesn't.

Node.js

In any Node.js application, you can use the X-Ray SDK for Node.js classes to instrument incoming requests, AWS SDK clients, and outgoing HTTP calls. Automatic request instrumentation is available for applications that use the Express framework.

See The X-Ray SDK for Node.js for more information.

  • Express – Use the X-Ray SDK for Node.js Express middleware to instrument incoming requests.

  • Other frameworks – Manually create segments and make sampling decisions on incoming requests.

C#

On Windows Server editions other than Windows Server Core, you can use the X-Ray SDK for .NET to instrument incoming requests, AWS SDK clients, and outgoing HTTP calls.

See The AWS X-Ray SDK for .NET for more information.

  • .NET on Windows Server – Add a message handler to your HTTP configuration to instrument incoming requests.

If the X-Ray SDK is not available for your language or platform, you can generate trace data manually and send it to the X-Ray daemon, or directly to the X-Ray API.

Supported AWS Services

Several AWS services provide X-Ray integration. Integrated services offer varying levels of integration that can include sampling and adding headers to incoming requests, running the X-Ray daemon, and automatically sending trace data to X-Ray.

  • Active instrumentation – Samples and instruments incoming requests.

  • Passive instrumentation – Instruments requests that have been sampled by another service.

  • Request tracing – Adds a tracing header to all incoming requests and propagates it downstream.

  • Tooling – Runs the AWS X-Ray daemon to receive segments from the X-Ray SDK.

Services with X-Ray integration include:

  • Amazon API Gateway – Request tracing. API Gateway passes the trace ID to AWS Lambda and adds it to the request header for other downstream services.

  • Elastic Load Balancing – Request tracing on application load balancers. The application load balancer adds the trace ID to the request header before sending it to a target group.

  • AWS Elastic Beanstalk – Tooling. Elastic Beanstalk includes the X-Ray daemon on the following platforms:

    • Java SE – 2.3.0 and newer configurations

    • Tomcat – 2.4.0 and newer configurations

    • Node.js – 3.2.0 and newer configurations

    • Windows Server – All configurations other than Windows Server Core released since December 9th, 2016.

    You can tell Elastic Beanstalk to run the daemon on the above platforms in the Elastic Beanstalk console, or by with the XRayEnabled option in the aws:elasticbeanstalk:xray namespace.

Code and Configuration Changes

A large amount of tracing data can be generated without any functional changes to your code. Detailed tracing of frontend and downstream calls require only minimal changes to build and deploy-time configuration.

Examples of Code and Configuration Changes

  • AWS resource configuration – Run the X-Ray daemon on the instances in your Elastic Beanstalk environment by changing an option setting.

  • Build configuration – Take X-Ray SDK for Java submodules as a compile-time dependency to instrument all downstream requests to AWS Services and resources such as Amazon DynamoDB tables, Amazon SQS queues, and Amazon S3 buckets.

  • Application configuration – To instrument incoming HTTP requests, add a servlet filter to your Java application, or use the X-Ray SDK for Node.js as middleware on your Express application. Change sampling rules and enable plugins to instrument the Amazon EC2, Amazon ECS, and AWS Elastic Beanstalk resources that run your application.

  • Class or object configuration – Import the X-Ray SDK for Java version of HttpClientBuilder instead of the Apache.org version to instrument outgoing HTTP calls in Java.

  • Functional changes – Add a request handler to an AWS SDK client to instrument calls that it makes to AWS services. Create subsegments to group downstream calls, add debug information to segments with annotations and metadata.