Configuring the X-Ray SDK for Ruby

The X-Ray SDK for Ruby has a class named XRay.recorder that provides the global recorder. You can configure the global recorder to customize the middleware that creates segments for incoming HTTP calls.

Service plugins

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

To use plugins, specify it in the configuration object that you pass to the recorder.

my_plugins = %I[ec2 elastic_beanstalk]

config = {
  plugins: my_plugins,
  name: 'my app',
}

XRay.recorder.configure(config)

You can also use environment variables, which take precedence over values set in code, to configure the recorder.

The SDK also uses plugin settings to set the origin field on the segment. This indicates the type of Amazon resource that runs your application. 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.

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.

{
  "version": 2,
  "rules": [
    {
      "description": "Player moves.",
      "host": "*",
      "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 for paths under /api/move/. 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.

To configure backup rules, define a hash for the document in the configuration object that you pass to the recorder.

require 'aws-xray-sdk'
my_sampling_rules =  {
  version: 1,
  default: {
    fixed_target: 1,
    rate: 0.1
  }
}
config = {
  sampling_rules: my_sampling_rules,
  name: 'my app',
}
XRay.recorder.configure(config)

To store the sampling rules independently, define the hash in a separate file and require the file to pull it into your application.

my_sampling_rules =  {
  version: 1,
  default: {
    fixed_target: 1,
    rate: 0.1
  }
}

require 'aws-xray-sdk'
require 'config/sampling-rules.rb'

config = {
  sampling_rules: my_sampling_rules,
  name: 'my app',
}
XRay.recorder.configure(config)

To use only local rules, require the sampling rules and configure the LocalSampler.

require 'aws-xray-sdk'
require 'aws-xray-sdk/sampling/local/sampler'

config = {
  sampler: LocalSampler.new,
  name: 'my app',
}
XRay.recorder.configure(config)

You can also configure the global recorder to disable sampling and instrument all incoming requests.

require 'aws-xray-sdk'
config = {
  sampling: false,
  name: 'my app',
}
XRay.recorder.configure(config)

Logging

By default, the recorder outputs info-level events to $stdout. You can customize logging by defining a logger in the configuration object that you pass to the recorder.

require 'aws-xray-sdk'
config = {
  logger: my_logger,
  name: 'my app',
}
XRay.recorder.configure(config)

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

Recorder configuration in code

Additional settings are available from the configure method on XRay.recorder.

require 'aws-xray-sdk'
config = {
  context_missing: 'LOG_ERROR'
}

XRay.recorder.configure(config)

Recorder configuration with rails

If you use the Rails framework, you can configure options on the global recorder in a Ruby file under app_root/initializers. The X-Ray SDK supports an additional configuration key for use with Rails.

Configure the available settings in a configuration object named Rails.application.config.xray.

Rails.application.config.xray = {
  name: 'my app',
  patch: %I[net_http aws_sdk],
  active_record: true
}

Environment variables

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

Environment variables override values set in code.