AWS X-Ray Use Cases and Requirements

You can use the X-Ray SDK and AWS service integration to instrument requests to your
applications that are running locally or on AWS compute services such as Amazon EC2,
Elastic Beanstalk, Amazon ECS and
AWS Lambda.

To instrument your application code, you 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 from
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, AWS Lambda can send trace data about requests to your Lambda functions, and
run the
X-Ray daemon on workers to make it easier to use the X-Ray SDK.

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. To do this, you add the X-Ray SDK for Java's filter to your servlet
configuration, and take the AWS SDK for Java 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.

C#

On Windows Server, you can use the X-Ray SDK for .NET to instrument incoming requests,
AWS
SDK clients, SQL clients, and HTTP clients. On AWS Lambda, you can use the Lambda
X-Ray
integration to instrument incoming requests.

In any Go application, you can use the X-Ray SDK for Go classes to instrument incoming
requests, AWS SDK clients, SQL clients, and HTTP clients. Automatic request instrumentation
is available for applications that use HTTP handlers.

On AWS Lambda, you can use the Lambda X-Ray integration to instrument incoming requests.
Add the X-Ray SDK for Go to your function for full instrumentation.

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

On AWS Lambda, you can use the Lambda X-Ray integration to instrument incoming requests.
Add the X-Ray SDK for Java to your function for full instrumentation.

Other frameworks – Add a servlet filter if
your framework supports servlets, or manually create a segment for each incoming
request.

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, SQL clients, and HTTP clients. Automatic request
instrumentation is available for applications that use the Express and Restify
frameworks.

On AWS Lambda, you can use the Lambda X-Ray integration to instrument incoming requests.
Add the X-Ray SDK for Node.js to your function for full instrumentation.

Other frameworks – Manually create a segment
for each incoming request.

Python

In any Python application, you can use the X-Ray SDK for Python classes to instrument
incoming requests, AWS SDK clients, SQL clients, and HTTP clients. Automatic request
instrumentation is available for applications that use the Django and Flask
frameworks.

On AWS Lambda, you can use the Lambda X-Ray integration to instrument incoming requests.
Add the X-Ray SDK for Python to your function for full instrumentation.

Other frameworks – Manually create a segment
for each incoming request.

Ruby

In any Ruby application, you can use the X-Ray SDK for Ruby classes to instrument
incoming
requests, AWS SDK clients, SQL clients, and HTTP clients. Automatic request instrumentation
is available for applications that use the Rails framework.

Rails – Add the X-Ray SDK for Ruby gem and railtie
to your gemfile, and configure the
recorder in an initializer to instrument 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 X-Ray daemon to receive segments from the
X-Ray SDK.

The following services provide X-Ray integration:

AWS Lambda – Active and passive instrumentation of incoming
requests on all runtimes. AWS Lambda adds two nodes to your service map, one for the
AWS Lambda service, and one
for the function. When you enable instrumentation, AWS Lambda also runs the X-Ray
daemon on Java and Node.js
runtimes for use with the X-Ray SDK. Learn more.

Amazon API Gateway – Active and passive instrumentation. API Gateway uses
sampling rules to determine which requests to record, and adds a node for the gateway
stage to your service
map. Learn more.

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

Java SE – 2.3.0 and later configurations

Tomcat – 2.4.0 and later configurations

Node.js – 3.2.0 and later configurations

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

You can use the Elastic Beanstalk console tell Elastic Beanstalk to run the daemon
on these platforms, or use the
XRayEnabled option in the aws:elasticbeanstalk:xray namespace. Learn more.

Code and Configuration Changes

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

Examples of Code and Configuration Changes

AWS resource configuration – Change AWS
resource settings to instrument requests to a Lambda function. 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 to resources such as Amazon DynamoDB tables, Amazon SQS queues, and
Amazon S3
buckets.

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

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, and add debug information to segments with annotations and
metadata.

Javascript is disabled or is unavailable in your browser.

To use the AWS Documentation, Javascript must be enabled. Please refer to your browser's
Help pages for instructions.