Aws xray java

Aws xray java DEFAULT

Tracing AWS SDK calls with the X-Ray SDK for Java

When your application makes calls to AWS services to store data, write to a queue, or send notifications, the X-Ray SDK for Java tracks the calls downstream in subsegments. Traced AWS services and resources that you access within those services (for example, an Amazon S3 bucket or Amazon SQS queue), appear as downstream nodes on the service map in the X-Ray console.

The X-Ray SDK for Java automatically instruments all AWS SDK clients when you include the and an submodules in your build. If you don't include the Instrumentor submodule, you can choose to instrument some clients while excluding others.

To instrument individual clients, remove the submodule from your build and add an as a on your AWS SDK client using the service's client builder.

For example, to instrument an client, pass a tracing handler to .

Example - DynamoDB client

For all services, you can see the name of the API called in the X-Ray console. For a subset of services, the X-Ray SDK adds information to the segment to provide more granularity in the service map.

For example, when you make a call with an instrumented DynamoDB client, the SDK adds the table name to the segment for calls that target a table. In the console, each table appears as a separate node in the service map, with a generic DynamoDB node for calls that don't target a table.

Example Subsegment for a call to DynamoDB to save an item

When you access named resources, calls to the following services create additional nodes in the service map. Calls that don't target specific resources create a generic node for the service.

  • Amazon DynamoDB – Table name

  • Amazon Simple Storage Service – Bucket and key name

  • Amazon Simple Queue Service – Queue name

To instrument downstream calls to AWS services with AWS SDK for Java and later, you can omit the module from your build configuration. Include the instead, then instrument individual clients by configuring them with a .

Example AWS SDK for Java and later - tracing interceptor


AWS X-Ray SDK for Java

Build Status

Screenshot of the AWS X-Ray console


The AWS X-Ray SDK for Java is compatible with Java 8 and

Add the AWS X-Ray SDK dependencies to your pom.xml:

Getting Help

Please use these community resources for getting help. We use the GitHub issues for tracking bugs and feature requests.

Opening Issues

If you encounter a bug with the AWS X-Ray SDK for Java we would like to hear about it. Search the existing issues and see if others are also experiencing the issue before opening a new issue. Please include the version of AWS X-Ray SDK for Java, AWS SDK for Java, JDK, and OS you’re using. Please also include repro case when appropriate.

The GitHub issues are intended for bug reports and feature requests. For help and questions with using AWS X-Ray SDK for Java please make use of the resources listed in the Getting Help section. Keeping the list of open issues lean will help us respond in a timely manner.


The developer guide provides in-depth guidance on using the AWS X-Ray service and the AWS X-Ray SDK for Java.

See awslabs/eb-java-scorekeep for a sample application that uses this SDK.

Quick Start

Intercept incoming HTTP requests

For many applications, work on a task begins with an incoming HTTP request.

There are a few different options for intercepting this incoming HTTP request.

Applications using may utilize the

Add the filter in Tomcat's :

Alternatively, Spring users may add the to their :

The servlet filter will fail to serve incoming requests if a is not supplied, either through web.xml init-params or through the constructor.

Applications not using may include custom interceptors to begin and end trace segments

Directly call and as necessary. Note: this method requires additional work to ensure that the header is properly propogated and sufficient information about the request and response is captured with the segment.

Intercept AWS requests

Applications may make calls to Amazon Web Services. Included in the X-Ray SDK is an extension of the AWS SDK's .

To instrument an example instance of :

Intercept outgoing HTTP requests

Applications may make downstream HTTP calls to communicate with other applications. If these downstream applications are also traced, trace context information will need to be passed so that the trace segments may be properly grouped into a single trace.

The following options are available for ensuring these downstream calls include trace context information as well as locally generate the appropriate trace subsegments.

Applications using Apache's library may utilize proxy classes included in

Change the import line for your or to the appropriate proxy import. Continue to use the class as normal; method signatures do not change.

Intercept JDBC-Based SQL Queries

In addition to our Postgres and MySQL patchers documented in the official docs, this SDK also includes the library. This library can instrument any JDBC data source, connection, or statement so that its queries are recorded by AWS X-Ray.

importcom.amazonaws.xray.sql.TracingConnection; importcom.amazonaws.xray.sql.TracingDataSource; importcom.amazonaws.xray.sql.TracingStatement; importjava.sql.*; // Choose the one that you'd like to traceString sql ="SELECT * FROM MYTABLE"; DataSource dataSource =TracingDataSource.decorate(dataSource); Connection connection =TracingConnection.decorate(connection); Statement statement =TracingStatement.decorateStatement(statement); PreparedStatement preparedStatement =TracingStatement.decoratePreparedStatement(preparedStatement, sql); CallableStatement callableStatement =TracingStatement.decorateCallableStatement(callableStatement, sql);

For security reasons, the SQL query is not recorded by default. However, you can opt-in to SQL query recording by setting the environment variable or the system property to .

Intercept custom methods

It may be useful to further decorate portions of an application for which performance is critical. Generating subsegments around these hot spots will help in understanding their impact on application performance. There are a few different styles available for tracing custom methods.

Using traced closures
Using explicit calls to begin and end subsegments.

Note that in the closure-based example above, exceptions are intercepted automatically.

Integration with ServiceLens

As of version , the X-Ray SDK for Java is integrated with CloudWatch ServiceLens. This allows you to use a wide range of new observability features which connect your traces, logs, and metrics in one place.

Trace ID Injection into Logs

You can automatically inject your current Trace ID into logging statements if you use the Log4J or SLF4J logging frontends. To learn more and enable this feature on your instrumented project, see the developer guide.

Vended Segment-Level Metrics

The X-Ray SDK can now automatically vend metrics that aggregate information about the segments your application sends as a custom CloudWatch metric. To learn more and enable this feature on your instrumented project, see the developer guide.

Log Group Correlation

If you are working in an environment with a supported plugin enabled and you use CloudWatch logs, the X-Ray SDK will automatically record the log group(s) you are using in that environment in the segment document. To learn more and see which plugins are supported, see the developer guide.


Snapshots are published for each commit to AWS Sonatype snapshots repository at

Building From Source

Once you check out the code from GitHub, you can build it using Maven. To disable the GPG-signing in the build, use:


The AWS X-Ray SDK for Java is licensed under the Apache License. See LICENSE and NOTICE.txt for more information.

  1. Camper shell clamps
  2. Wii classic controller
  3. Personalized motorcycle name art
  4. Av chevy used cars

AWS X-Ray auto-instrumentation agent for Java

The AWS X-Ray auto-instrumentation agent for Java is a tracing solution that instruments your Java web applications with minimal development effort. The agent enables tracing for servlet-based applications and all of the agent's downstream requests made with supported frameworks and libraries. This includes downstream Apache HTTP requests, AWS SDK requests, and SQL queries made using a JDBC driver. The agent propagates X-Ray context, including all active segments and subsegments, across threads. All of the configurations and versatility of the X-Ray SDK are still available with the Java agent. Suitable defaults were chosen to ensure that the agent works with minimal effort.

The X-Ray agent solution is best suited for servlet-based, request-response Java web application servers. If your application uses an asynchronous framework, or is not well modeled as a request-response service, you might want to consider manual instrumentation with the SDK instead. 

The X-Ray agent is built using the Distributed Systems Comprehension toolkit, or DiSCo. DiSCo is an open source framework for building Java agents that can be used in distributed systems. While it is not necessary to understand DiSCo to use the X-Ray agent, you can learn more about the project by visiting its homepage on GitHub. The X-Ray agent is also fully open-sourced. To view the source code, make contributions, or raise issues about the agent, visit its repository on GitHub.

Sample application

The eb-java-scorekeep sample application is adapted to be instrumented with the X-Ray agent. This branch contains no servlet filter or recorder configuration, as these functions are done by the agent. To run the application locally or using AWS resources, follow the steps in the sample application's readme file. The instructions for using the sample app to generate X-Ray traces are in the sample app’s tutorial.

Getting started

To get started with the X-Ray auto-instrumentation Java agent in your own application, follow these steps.

  1. Run the X-Ray daemon in your environment. For more information, see X-Ray daemon.

  2. Download the latest distribution of the agent. Unzip the archive and note its location in your file system. Its contents should look like the following.

    disco ├── disco-java-agent.jar └── disco-plugins     ├── aws-xray-agent-plugin.jar     ├── disco-java-agent-aws-plugin.jar     ├── disco-java-agent-sql-plugin.jar     └── disco-java-agent-web-plugin.jar
  3. Modify the JVM arguments of your application to include the following, which enables the agent. Ensure the argument is placed before the argument if applicable. The process to modify JVM arguments varies depending on the tools and frameworks you use to launch your Java server. Consult the documentation of your server framework for specific guidance.

  4. To specify how the name of your application appears on the X-Ray console, set the  environment variable or the  system property. If no name is provided, a default name is used.

  5. Restart your server or container. Incoming requests and their downstream calls are now traced. If you don’t see the expected results, see Troubleshooting.


The X-Ray agent is configured by an external, user-provided JSON file. By default, this file is at the root of the user’s classpath (for example, in their  directory) named . You can configure a custom location for the config file by setting the system property to the absolute filesystem path of your configuration file.

An example configuration file is shown next.

Configuration specification

The following table describes valid values for each property. Property names are case sensitive, but their keys are not. For properties that can be overridden by environment variables and system properties, the order of priority is always environment variable, then system property, and then configuration file. See the Environment Variables for information about properties that you can override. All fields are optional.

Property name Type Valid values Description Environment variable System property Default



Any string

The name of your instrumented service as it will appear in the X-Ray console.







The action taken by the agent when it attempts to use the X-Ray segment context but none is present.






Formatted IP address and port, or list of TCP and UDP address

The address the agent uses to communicate with the X-Ray daemon.





True, False

Enables instrumentation by the X-Ray agent.







The sampling strategy used by the agent. ALL captures all requests, NONE captures no requests. See sampling rules.






Any string

Includes the provided prefix before injected trace IDs in logs.



None (empty string)



An absolute file path

The path to a custom sampling rules file to be used as the source of sampling rules for the local sampling strategy, or the fallback rules for the central strategy.






An absolute file path

The path to a custom parameter allow list, which captures additional information from AWS SDK clients.






1, 2

Version of the AWS SDK for Java you’re using. Ignored if  is not also set.






Non-negative integers

The maximum lines of a stack trace to record in a trace.






Non-negative integers

After at least this many subsegments are closed, they are streamed to the daemon out-of-band to avoid chunks being too large.





True, False

Enables X-Ray trace ID injection into logs if the dependencies and configuration described in logging config are also added. Otherwise, does nothing.






True, False

Enables plugins that record metadata about the AWS environments you’re operating in. See plugins.






True, False

Records SQL query strings in SQL subsegments on a best-effort basis.






True, False

Automatically propagates X-Ray context between threads if true. Otherwise, uses Thread Local to store context and manual propagation across threads is required.




Logging configuration

The X-Ray agent's log level can be configured in the same way as the X-Ray SDK for Java. See Logging for more information on configuring logging with the X-Ray SDK for Java.

Manual instrumentation

If you’d like to perform manual instrumentation in addition to the agent’s auto-instrumentation, add the X-Ray SDK as a dependency to your project. Note that the SDK's custom servlet filters mentioned in Tracing Incoming Requests are not compatible with the X-Ray agent.


You must use the latest version of the X-Ray SDK to perform manual instrumentation while also using the agent.

If you are working in a Maven project, add the following dependencies to your  file.

If you are working in a Gradle project, add the following dependencies to your  file.

You can add custom subsegments in addition to annotations, metadata, and user IDs while using the agent, just as you would with the normal SDK. The agent automatically propagates context across threads, so no workarounds to propagate context should be necessary when working with multithreaded applications.


Since the agent offers fully automatic instrumentation, it can be difficult to identify the root cause of a problem when you are experiencing issues. If the X-Ray agent is not working as expected for you, review the following problems and solutions. The X-Ray agent and SDK use Jakarta Commons Logging (JCL). To see the logging output, ensure that a bridge connecting JCL to your logging backend is on the classpath, as in the following example: or .

Problem: I’ve enabled the Java agent on my application but don’t see anything on the X-Ray console

Is the X-Ray daemon running on the same machine?

If not, see the X-Ray daemon documentation to set it up.

In your application logs, do you see a message like "Initializing the X-Ray agent recorder"?

If you have correctly added the agent to your application, this message is logged at INFO level when your application starts, before it starts taking requests. If this message is not there, then the Java agent is not running with your Java process. Make sure you’ve followed all the setup steps correctly with no typos.

In your application logs, do you see several error messages saying something like "Suppressing AWS X-Ray context missing exception"?

These errors occur because the agent is trying to instrument downstream requests, like AWS SDK requests or SQL queries, but the agent was unable to automatically create a segment. If you see many of these errors, the agent might not be the best tool for your use case and you might want to consider manual instrumentation with the X-Ray SDK instead. Alternatively, you can enable X-Ray SDK debug logs to see the stack trace of where the context-missing exceptions are occurring. You can wrap these portions of your code with custom segments, which should resolve these errors. For an example of wrapping downstream requests with custom segments, see the sample code in instrumenting startup code.

Problem: Some of the segments I expect do not appear on the X-Ray console

Does your application use multithreading?

If some segments that you expect to be created are not appearing in your console, background threads in your application might be the cause. If your application performs tasks using background threads that are “fire and forget,” like making a one-off call to a Lambda function with the AWS SDK, or polling some HTTP endpoint periodically, that may confuse the agent while it is propagating context across threads. To verify this is your problem, enable X-Ray SDK debug logs and check for messages like: Not emitting segment named <NAME > as it parents in-progress subsegments. To work around this, you can try joining the background threads before your server returns to ensure all the work done in them is recorded. Or, you can set the agent’s configuration to to disable context propagation in background threads. If you do this, you’ll have to manually instrument those threads with custom segments or ignore the context missing exceptions they produce.

Have you set up sampling rules?

If there are seemingly random or unexpected segments appearing on the X-Ray console, or the segments you expect to be on the console aren’t, you might be experiencing a sampling issue. The X-Ray agent applies centralized sampling to all segments it creates, using the rules from the X-Ray console. The default rule is 1 segment per second, plus 5% of segments afterward, are sampled. This means segments that are created rapidly with the agent might not be sampled. To resolve this, you should create custom sampling rules on the X-Ray console that appropriately sample the desired segments. For more information, see sampling.


AWS X-Ray Java Agent

Build Status

Screenshot of the AWS X-Ray console

The AWS X-Ray Java Agent is a drop-in solution that enables the propagation of X-Ray traces within your Java web applications and servlet-based microservices. This includes automatic tracing for supported frameworks and libraries, including Spring, the AWS SDK, Apache HTTP clients, and JDBC-based SQL queries. The agent enables you to use the X-Ray SDK out of box, and requires no code changes to enable the basic propagation of traces. See the chart below for the current feature parity between the AWS X-Ray SDK and the AWS X-Ray Java Agent.

The X-Ray Java Agent is implemented using the DiSCo library, a toolkit for building Java Agents in distributed environments.

Compatibility Chart


The AWS X-Ray Java Agent is compatible with Java 8 and You must be able to modify the JVM arguments of your application to use the agent.


You can download the latest version of the X-Ray Agent here, or you can browse the releases to download earlier versions.

Alternatively, you can download the agent from Maven Central by adding a dependency on it. This approach is not recommended because you will be responsible for assembling all the JARs into the required file structure. To depend on the agent from your project, just add these dependencies:

<dependencies> <dependency> <groupId></groupId> <artifactId>disco-toolkit-bom</artifactId> <version></version> <type>pom</type> <scope>import</scope> </dependency> <dependency> <groupId></groupId> <artifactId>disco-java-agent</artifactId> </dependency> <dependency> <groupId></groupId> <artifactId>disco-java-agent-aws-plugin</artifactId> </dependency> <dependency> <groupId></groupId> <artifactId>disco-java-agent-sql-plugin</artifactId> </dependency> <dependency> <groupId></groupId> <artifactId>disco-java-agent-web-plugin</artifactId> </dependency> <dependency> <groupId>com.amazonaws</groupId> <artifactId>aws-xray-agent-plugin</artifactId> <version></version> </dependency> </dependencies>

To get started with the agent in your application, see the official documentation.

Sample App

To see the Agent in action first, checkout the branch of the eb-java-scorekeep. The README has steps to set up a fully-functioning Spring Boot application instrumented with the X-Ray Agent and complemented with manual instrumentation by the X-Ray SDK.

Performance impacts

To get an idea of how much impact the X-Ray Agent might have on your system, please see the benchmarking package.

Customizing the Agent


The X-Ray Agent is configured by an external, user-provided JSON file. By default this file is expected to be located at the root of the user's classpath and titled . You can configure a custom location for the config file by setting the system property to the absolute filesystem path OR absolute location on the classpath of your configuration file.

For more details about configuring the agent, see the official documentation.

Toggling Tracing for Different Events

The benefit of the X-Ray Agent operating as a plugin rather than a monolith is that you can add or remove other compatible DiSCo plugins as you please. All of the plugins that the X-Ray agent will use are in the directory pointed to by the parameter in your JVM argument. The plugins are what instrument different events like AWS SDK requests and SQL queries so they can be traced by X-Ray. Normally, this is the directory in the ZIP distribution, but it can be any directory.

To remove an undesirable plugin, simply remove it from your directory and restart your app. For example, to disable tracing of SQL queries, remove the from your .

To add new DiSCo plugins, just add them as a JAR to your directory and restart your app. For example, if a plugin to intercept HTTP requests made with OkHTTP was developed, you should be able to just build the plugin and add the JAR to your . No additional configuration from the agent should be required, but feel free to open an issue if it doesn't work out of the box.


When troubleshooting the agent, one of the first steps is to enable logging for the agent. The agent uses Apache Commons Logging, so you may need to add a bridge like or to your classpath to see logs. To configure the log level, set this system property:

If your problem cannot be diagnosed with X-Ray logs, then DiSCo logs could help too. To enable DiSCo logs, append the classpath of the DiSCo logger to your JVM argument that's enabling the X-Ray agent, like so:

For more troubleshooting steps, see the official documentation.

Developing on the Agent

Structure of this repo

This repository contains the X-Ray Agent as a DiSCo plugin. Note that this is NOT a proper Java agent with a premain and bytecode manipulation. Rather it is a plugin to extend the functionality of a proper Java agent like the one described. To learn more about DiSCo plugins and how they work with the DiSCo java agent, see the DiSCo documentation.

The layout of this project is:

- The source code of the AWS X-Ray agent plugin. This contains the hooks that allow our plugin to communicate with the DiSCo Agent. It is also where instrumentation using the X-Ray SDK happens.

- This package contains no source code. It only uses a series of build rules to bundle the above source code into a JAR that represents a DiSCo plugin, run integration tests against that JAR, then finally bundle that JAR and all needed DiSCo dependencies into an archive for the end user.

- This package also contains no source code. It runs tests to compare the performance of the X-Ray Agent and the X-Ray SDK.

Building from Source

If there are unreleased changes on the branch that you'd like to try out early, you can build the agent from its source code. The agent uses Gradle to manage its builds and produce the artifact that is ultimately distributed with releases. You can build the agent distribution locally by running the following commands:

git clone cd aws-xray-java-agent/ ./gradlew build

Now, the latest changes on will be bundled into a ZIP file located at . This ZIP file is structured the same as the one described in the installation documentation, so you can follow those instructions using this artifact. For example, if you'd like to extract the X-Ray Agent JAR and its dependencies to use in your project, you could run the following commands:

cd aws-xray-agent-plugin/build/dist/ unzip # Unpackages Agent JAR and disco dependencies into a disco directory cp -r disco /path/to/your/project # Copies the disco directory for use in your project with the -javaagent argument

Getting Help

Please use these community resources for getting help.


The AWS X-Ray SDK Java Agent is licensed under the Apache License. See LICENSE and NOTICE.txt for more information.


Java aws xray

Configuring the X-Ray SDK for Java

The X-Ray SDK for Java includes a class named that provides the global recorder. This is a that you can use to instrument your code. You can configure the global recorder to customize the that creates segments for incoming HTTP calls.

Service plugins

Use to record information about the service hosting your application.


  • Amazon EC2 – adds the instance ID, Availability Zone, and the CloudWatch Logs Group.

  • Elastic Beanstalk – adds the environment name, version label, and deployment ID.

  • Amazon ECS – adds the container ID.

  • Amazon EKS – adds the container ID, cluster name, pod ID, and the CloudWatch Logs Group.

To use a plugin, call on your .

The SDK also uses plugin settings to set the field on the segment. This indicates the type of AWS resource that runs your application. The resource type appears under your application's name in the service map. For example, .

When you use multiple plugins, the SDK uses the following resolution order to determine the origin: ElasticBeanstalk > EKS > ECS > EC2.

Sampling rules

The SDK uses the sampling rules you define in the X-Ray console to determine which requests to record. The default rule traces the first request each second, and five percent of any additional requests across all services sending traces to X-Ray. Create additional rules in the X-Ray console to customize the amount of data recorded for each of your applications.

The SDK applies custom rules in the order in which they are defined. If a request matches multiple custom rules, the SDK applies only the first rule.


If the SDK can't reach X-Ray to get sampling rules, it reverts to a default local rule of the first request each second, and five percent of any additional requests per host. This can occur if the host doesn't have permission to call sampling APIs, or can't connect to the X-Ray daemon, which acts as a TCP proxy for API calls made by the SDK.

You can also configure the SDK to load sampling rules from a JSON document. The SDK can use local rules as a backup for cases where X-Ray sampling is unavailable, or use local rules exclusively.

Example sampling-rules.json

This example defines one custom rule and a default rule. The custom rule applies a five-percent sampling rate with no minimum number of requests to trace for paths under . The default rule traces the first request each second and 10 percent of additional requests.

The disadvantage of defining rules locally is that the fixed target is applied by each instance of the recorder independently, instead of being managed by the X-Ray service. As you deploy more hosts, the fixed rate is multiplied, making it harder to control the amount of data recorded.

On AWS Lambda, you cannot modify the sampling rate. If your function is called by an instrumented service, calls that generated requests that were sampled by that service will be recorded by Lambda. If active tracing is enabled and no tracing header is present, Lambda makes the sampling decision.

To provide backup rules in Spring, configure the global recorder with a in a configuration class.

For Tomcat, add a listener that extends and register the listener in the deployment descriptor.

Example src/com/myapp/web/

Example WEB-INF/web.xml

To use local rules only, replace the with a .


By default, the SDK outputs -level messages to your application logs. You can enable debug-level logging on the SDK to output more detailed logs to your application log file. Valid log levels are , , , , and . log level silences all log messages because the SDK does not log at fatal level.


Set the logging level with the property.

Use debug logs to identify issues, such as unclosed subsegments, when you generate subsegments manually.

Trace ID injection into logs

To expose the current fully qualified trace ID to your log statements, you can inject the ID into the mapped diagnostic context (MDC). Using the interface, methods are called from the X-Ray recorder during segment lifecycle events. When a segment or subsegment begins, the qualified trace ID is injected into the MDC with the key . When that segment ends, the key is removed from the MDC. This exposes the trace ID to the logging library in use. When a subsegment ends, its parent ID is injected into the MDC.

Example fully qualified trace ID

The fully qualified ID is represented as

This feature works with Java applications instrumented with the AWS X-Ray SDK for Java, and supports the following logging configurations:

  • SLF4J front-end API with Logback backend

  • SLF4J front-end API with Log4J2 backend

  • Log4J2 front-end API with Log4J2 backend

See the following tabs for the needs of each front end and each backend.

Trace ID Injection Example

The following shows a string modified to include the trace ID. The trace ID is printed after the thread name () and before the log level ().

Example With ID injection

AWS X-Ray automatically prints the key and the trace ID in the log statement for easy parsing. The following shows a log statement using the modified .

Example Log statement with ID injection

The logging message itself is housed in the pattern and is set when calling the logger.

Segment listeners

Segement listeners are an interface to intercept lifecycle events such as the beginning and ending of segments produced by the . Implementation of a segment listener event function might be to add the same annotation to all subsegments when they are created with , log a message after each segment is sent to the daemon using , or to record queries sent by the SQL interceptors using to verify if the subsegment represents an SQL query, adding additional metadata if so.

To see the full list of functions, visit the documentation for the AWS X-Ray Recorder SDK for Java API.

The following example shows how to add a consistent annotation to all subsegments on creation with and to print a log message at the end of each segment with .


This custom segment listener is then referenced when building the .

Example AWSXRayRecorderBuilder statement

Environment variables

You can use environment variables to configure the X-Ray SDK for Java. The SDK supports the following variables.

  • – Set a service name that the SDK uses for segments. Overrides the service name that you set on the servlet filter's segment naming strategy.

  • – Set the host and port of the X-Ray daemon listener. By default, the SDK uses for both trace data (UDP) and sampling (TCP). Use this variable if you have configured the daemon to listen on a different port or if it is running on a different host.


    • Same port

    • Different ports

  • – Set to to avoid throwing exceptions when your instrumented code attempts to record data when no segment is open.

    Valid Values

    • – Throw a runtime exception (default).

    • – Log an error and continue.

    Errors related to missing segments or subsegments can occur when you attempt to use an instrumented client in startup code that runs when no request is open, or in code that spawns a new thread.

Environment variables override equivalent system properties and values set in code.

System properties

You can use system properties as a JVM-specific alternative to environment variables. The SDK supports the following properties:

  • – Equivalent to .

  • – Equivalent to .

  • – Equivalent to .

If both a system property and the equivalent environment variable are set, the environment variable value is used. Either method overrides values set in code.

AWS X-Ray: Analyze, Debug \u0026 Optimize Application Performance - Concept - Demo

AWS X-Ray SDK for Java

The X-Ray SDK for Java is a set of libraries for Java web applications that provide classes and methods for generating and sending trace data to the X-Ray daemon. Trace data includes information about incoming HTTP requests served by the application, and calls that the application makes to downstream services using the AWS SDK, HTTP clients, or an SQL database connector. You can also create segments manually and add debug information in annotations and metadata.

The X-Ray SDK for Java is an open source project. You can follow the project and submit issues and pull requests on GitHub:

Start by adding AWSXRayServletFilter as a servlet filter to trace incoming requests. A servlet filter creates a segment. While the segment is open, you can use the SDK client's methods to add information to the segment and create subsegments to trace downstream calls. The SDK also automatically records exceptions that your application throws while the segment is open.

Starting in release , you can instrument your application using aspect-oriented programming (AOP) in Spring. What this means is that you can instrument your application, while it is running on AWS, without adding any code to your application's runtime.

Next, use the X-Ray SDK for Java to instrument your AWS SDK for Java clients by including the SDK Instrumentor submodule in your build configuration. Whenever you make a call to a downstream AWS service or resource with an instrumented client, the SDK records information about the call in a subsegment. AWS services and the resources that you access within the services appear as downstream nodes on the service map to help you identify errors and throttling issues on individual connections.

If you don't want to instrument all downstream calls to AWS services, you can leave out the Instrumentor submodule and choose which clients to instrument. Instrument individual clients by adding a TracingHandler to an AWS SDK service client.

Other X-Ray SDK for Java submodules provide instrumentation for downstream calls to HTTP web APIs and SQL databases. You can use the X-Ray SDK for Java versions of HTTPClient and HTTPClientBuilder in the Apache HTTP submodule to instrument Apache HTTP clients. To instrument SQL queries, add the SDK's interceptor to your data source.

After you start using the SDK, customize its behavior by configuring the recorder and servlet filter. You can add plugins to record data about the compute resources running your application, customize sampling behavior by defining sampling rules, and set the log level to see more or less information from the SDK in your application logs.

Record additional information about requests and the work that your application does in annotations and metadata. Annotations are simple key-value pairs that are indexed for use with filter expressions, so that you can search for traces that contain specific data. Metadata entries are less restrictive and can record entire objects and arrays — anything that can be serialized into JSON.

Annotations and Metadata

Annotations and metadata are arbitrary text that you add to segments with the X-Ray SDK. Annotations are indexed for use with filter expressions. Metadata are not indexed, but can be viewed in the raw segment with the X-Ray console or API. Anyone that you grant read access to X-Ray can view this data.

When you have a lot of instrumented clients in your code, a single request segment can contain many subsegments, one for each call made with an instrumented client. You can organize and group subsegments by wrapping client calls in custom subsegments. You can create a custom subsegment for an entire function or any section of code, and record metadata and annotations on the subsegment instead of writing everything on the parent segment.


You can download the X-Ray SDK for Java from Maven. The X-Ray SDK for Java is split into submodules by use case, with a bill of materials for version management:

If you use Maven or Gradle to build your application, add the X-Ray SDK for Java to your build configuration.

For reference documentation of the SDK's classes and methods, see AWS X-Ray SDK for Java API Reference.


The X-Ray SDK for Java requires Java 8 or later, Servlet API 3, the AWS SDK, and Jackson.

The SDK depends on the following libraries at compile and runtime:

  • AWS SDK for Java version or later

  • Servlet API

These dependencies are declared in the SDK's file and are included automatically if you build using Maven or Gradle.

If you use a library that is included in the X-Ray SDK for Java, you must use the included version. For example, if you already depend on Jackson at runtime and include JAR files in your deployment for that dependency, you must remove those JAR files because the SDK JAR includes its own versions of Jackson libraries.

Dependency management

The X-Ray SDK for Java is available from Maven:

  • Group

  • Artifact

  • Version

If you use Maven to build your application, add the SDK as a dependency in your file.

Example pom.xml - dependencies

For Gradle, add the SDK as a compile-time dependency in your file.

Example build.gradle - dependencies

If you use Elastic Beanstalk to deploy your application, you can use Maven or Gradle to build on-instance each time you deploy, instead of building and uploading a large archive that includes all of your dependencies. See the sample application for an example that uses Gradle.


Now discussing:

Distributed Tracing using AWS X-Ray

As monoliths have been replaced by microservice applications, growing in size and complexity,
the challenge of troubleshooting and identifying performance issues has increased.
In addition, extensive usage of cloud platforms such as AWS to deploy microservice architectures make the code execution points highly elastic and dynamic. Traditional tools to capture and analyze information in a monolithic world become powerless in this new environment.
Architects and IT operations now require operational visibility into their entire architecture.

On AWS we can use distributed tracing services, such as AWS X-Ray, to collect and record traces as requests travel through the application, generate maps to see how requests flow across services, gain insight on the relationships between components, as well as identify and analyze issues in real time.

In this article we will see how we can setup distributed tracing for a sample application written in Spring Boot.
This is how it works:

  • The application need to implement the X-Ray Java SDK which generates and sends the tracing data to a X-Ray daemon service
  • The X-Ray daemon service will then send the data to the AWS X-Ray API
  • Tracing data is available on the AWS X-Ray Service Console

Maven dependencies

We need first to add the AWS X-Ray Java SDK to our pom.xml.

Tracing incoming requests

To trace all incoming requests to our microservice, first we configure a Servlet Filter provided by the SDK. Then we add the Servlet to our Spring configuration.

After adding the X-Ray servlet filter to our application, the X-Ray SDK for Java creates a segment for each incoming request with an block that contains the following information:

  • HTTP method: GET, POST, PUT, DELETE, etc.
  • Client address: The IP address of the client that sent the request.
  • Response code: The HTTP response code for the completed request.
  • Timing: The start time (when the request was received) and end time (when the response was sent).
  • User agent: The user-agent from the request.
  • Content length: The content-length from the response.

Tracing your spring bean components

The X-Ray SDK offers a non-invasive Spring integration way of tracing our Spring beans. This help us see the complete call stack of the application from the controller down through the back-end layers.

  • We need to add first a spring AOP Aspect that will catch your method's execution and generate your tracing metadata:

  • Let's annotate the spring components that we want to trace:

The @XRayEnabled annotation can be used on the class or method level for more fine-grained control.

Tracing your outbound HTTP calls

When making external calls to API's, we will need to use the AWS X-Ray Apache library which act as a wrapper to the Apache HttpComponents. This is the only time when we may have an impact on the existing code, especially if another HTTP client is used other than Apache like Spring Rest Template or HTTP Client (available since Java 11).

Before to deploy our microservice on AWS ECS, we need to setup the AWS X-Ray Daemon.
In this example the X-Ray Daemon will be running as a Sidecar Container using the X-Ray-Daemon container provided by AWS.
Our ECS task will have then two container definitions when the application container will send trace data on to the X-Ray Daemon container.


We also need to give the role permission to contact the AWS X-Ray API:

Please checkout this article on how to deploy a Spring Boot microservice on Amazon ECS using Github Actions.

X-Ray console uses trace data sent by the X-Ray daemon to generate a detailed service graph. The service graph can shows the client, front-end service, and backend services.

In this example we are tracing the client requests as they travel through the application which is comprised of 2 microservices:


The console provides a filter expression language for filtering requests, and services based on data in request headers, response status, and indexed fields on the tracing data.

The service graph helps identify bottlenecks and latency spikes as shown in the example bellow where we introduced a latency on the first microservice:


It also identify services where errors are occurring:


Exception logs are also available:


More details on the AWS X-Ray console can be found here

AWS X-Ray integrates natively with other AWS Services to increase the visibility of your architecture. The AWS X-Ray agent can also be run locally if some pieces of the application is deployed on-premises.

AWS X-Ray always encrypts traces at rest, and can also be configured to use AWS Key Management Service (AWS KMS) for compliance requirement like PCI and HIPAA.

Want to implement Distributed Tracing to monitor your architecture? Feel free to contact us. It would be a pleasure to help and work with you!



13790 13791 13792 13793 13794