Menu
AWS X-Ray
Developer Guide

Configuring the X-Ray SDK for Java

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

Service Plugins

Use plugins to record information about the service hosting your application.

  • Amazon EC2 – EC2Plugin adds the instance ID and Availability Zone.

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

  • Amazon ECS – ECSPlugin adds the cluster ID.

Segment resource data with Amazon EC2 and Elastic Beanstalk plugins.

To use a plugin, call withPlugin on your AWSXRayRecorderBuilder.

Example src/main/java/scorekeep/WebConfig.java - Recorder

import com.amazonaws.xray.AWSXRay;
import com.amazonaws.xray.AWSXRayRecorderBuilder;
import com.amazonaws.xray.plugins.EC2Plugin;
import com.amazonaws.xray.plugins.ElasticBeanstalkPlugin;
import com.amazonaws.xray.strategy.sampling.LocalizedSamplingStrategy;

@Configuration
public class WebConfig {
...
  static {
    AWSXRayRecorderBuilder builder = AWSXRayRecorderBuilder.standard().withPlugin(new EC2Plugin()).withPlugin(new ElasticBeanstalkPlugin());

    URL ruleFile = WebConfig.class.getResource("/sampling-rules.yml");
    builder.withSamplingStrategy(new LocalizedSamplingStrategy(ruleFile));

    AWSXRay.setGlobalRecorder(builder.build());
  }
}

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

Service node with resource type.

When you use multiple plugins, the SDK uses the last plugin loaded.

Sampling Rules

The SDK has a default sampling strategy that determines which requests get traced. By default, the SDK traces the first request each second, and 5 percent of any additional requests. You can customize the SDK's sampling behavior by applying rules defined in a local file.

Example sampling-rules.json

{
  "version": 1,
  "rules": [
    {
      "description": "Player moves.",
      "service_name": "*",
      "http_method": "*",
      "url_path": "/api/move/*",
      "fixed_target": 0,
      "rate": 0.05
    }
  ],
  "default": {
    "fixed_target": 1,
    "rate": 0.1
  }
}

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 to requests with paths under /api/move/. The default rule traces the first request each second and 10 percent of additional requests.

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.

For Spring, configure the global recorder in a configuration class.

Example src/main/java/myapp/WebConfig.java - Recorder Configuration

import com.amazonaws.xray.AWSXRay;
import com.amazonaws.xray.AWSXRayRecorderBuilder;
import com.amazonaws.xray.javax.servlet.AWSXRayServletFilter;
import com.amazonaws.xray.plugins.EC2Plugin;
import com.amazonaws.xray.strategy.sampling.LocalizedSamplingStrategy;

@Configuration
public class WebConfig {

  static {
  AWSXRayRecorderBuilder builder = AWSXRayRecorderBuilder.standard().withPlugin(new EC2Plugin());

  URL ruleFile = WebConfig.class.getResource("file://sampling-rules.json");
  builder.withSamplingStrategy(new LocalizedSamplingStrategy(ruleFile));

  AWSXRay.setGlobalRecorder(builder.build());
}

For Tomcat, add a listener that extends ServletContextListener.

Example src/com/myapp/web/Startup.java

package com.myapp.web;

import java.net.URL;

import javax.servlet.ServletContextEvent;
import javax.servlet.ServletContextListener;

import com.amazonaws.xray.AWSXRay;
import com.amazonaws.xray.AWSXRayRecorderBuilder;
import com.amazonaws.xray.plugins.EC2Plugin;
import com.amazonaws.xray.strategy.sampling.LocalizedSamplingStrategy;

public class Startup implements ServletContextListener {

    @Override
    public void contextInitialized(ServletContextEvent event) {
        AWSXRayRecorderBuilder builder = AWSXRayRecorderBuilder.standard().withPlugin(new EC2Plugin());

        URL ruleFile = Context.class.getResource("/sampling-rules.json");
        builder.withSamplingStrategy(new LocalizedSamplingStrategy(ruleFile));

        AWSXRay.setGlobalRecorder(builder.build());
    }

    @Override
    public void contextDestroyed(ServletContextEvent event) { }
}

Register the listener in the deployment descriptor.

Example WEB-INF/web.xml

...
  <listener>
    <listener-class>com.myapp.web.Startup</listener-class>
  </listener>

Logging

By default, the SDK outputs SEVERE and ERROR 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.

Example application.properties

Set the logging level with the logging.level.com.amazonaws.xray property.

logging.level.com.amazonaws.xray = DEBUG

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

Environment Variables

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

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

  • AWS_XRAY_DAEMON_ADDRESS – Set the IP address and port of the X-Ray daemon listener. By default, the SDK sends trace data to 127.0.0.1:2000. Use this variable if you have configured the daemon to listen on a different port.