The AWS X-Ray SDKs will enter maintenance mode on February 25, 2026. During maintenance mode, the X-Ray SDKs and Daemon will only receive critical bug fixes and security updates, and will not be updated to support new features.
We recommend that you migrate to AWS Distro for OpenTelemetry (ADOT) or OpenTelemetry Instrumentation to generate traces (through manual or zero-code instrumentation) from your application and send them to AWS X-Ray. OpenTelemetry is the industry-wide standard for tracing instrumentation and observability. It has a large open-source community for support and provides more instrumentations and updates. By adopting an OpenTelemetry solution, developers can leverage the latest services and innovations from AWS CloudWatch.
AWS X-Ray supports using OpenTelemetry Ruby and the AWS Distro for OpenTelemetry (ADOT) Collector to instrument your application and send trace data to X-Ray. The OpenTelemetry SDKs are an industry-wide standard for tracing instrumentation. They provide more instrumentations and have a larger community for support, but may not have complete feature parity with the X-Ray SDKs. See choosing between the ADOT and X-Ray SDKs for more help with choosing between the two. Note that using OpenTelemetry Ruby and ADOT is in public preview, and like this SDK in beta, is not recommended for production applications.
If you want additional features when tracing your Ruby applications, please open an issue on the OpenTelemetry Ruby Instrumentation repository.
The AWS X-Ray SDK for Ruby is compatible with Ruby 2.3.6 and newer Ruby versions. It has experimental support for JRuby 9.2.0.0 (still forthcoming).
To install the Ruby gem for your project, add it to your project Gemfile. You must also add either the Oj or JrJackson gems, for MRI and JRuby respectively, for JSON parsing. The default JSON parser will not work properly, currently.
# Gemfile
gem 'aws-xray-sdk'
gem 'oj', platform: :mri
gem 'jrjackson', platform: :jruby
Then run bundle install.
Use the following community resources for getting help with the SDK. We use the GitHub issues for tracking bugs and feature requests.
- Ask a question in the AWS X-Ray Forum.
- Open a support ticket with AWS Support.
- If you think you may have found a bug, open an issue.
If you encounter a bug with the AWS X-Ray SDK for Ruby, we want to hear about it. Before opening a new issue, search the existing issues to see if others are also experiencing the issue. Include the version of the AWS X-Ray SDK for Ruby, Ruby language, and other gems if applicable. In addition, include the repro case when appropriate.
The GitHub issues are intended for bug reports and feature requests. For help and questions about using the AWS SDK for Ruby, use the resources listed in the Getting Help section. Keeping the list of open issues lean helps us respond in a timely manner.
The developer guide provides in-depth guidance about using the AWS X-Ray service. The API Reference provides documentation for public APIs of all classes in the SDK.
Configuration
require'aws-xray-sdk'# For configuring sampling rules through X-Ray service# please see https://docs.aws.amazon.com/xray/latest/devguide/xray-console-sampling.html.# The doc below defines local fallback sampling rules which has lower priority.my_sampling_rules={version: 2,rules: [{description: 'healthcheck',host: '*',http_method: 'GET',url_path: '/ping',fixed_target: 0,rate: 0}],default: {fixed_target: 1,rate: 0.2}}user_config={sampling: true,sampling_rules: my_sampling_rules,name: 'default_segment_name',daemon_address: '127.0.0.1:3000',context_missing: 'LOG_ERROR',patch: %I[net_httpaws_sdk]}XRay.recorder.configure(user_config)Working with Lambda
# Bundle aws-xray-sdk with your code.# Require any aws-sdks and http libraries to be used, then...require'aws-xray-sdk/lambda'# aws-sdk and http calls from here on will be instrumentedSee also lib/aws-xray-sdk/lambda.rb
Working with Rails
# Edit Gemfile to add XRay middlewaregem'aws-xray-sdk',require: ['aws-xray-sdk/facets/rails/railtie']# Configure the recorder in app_root/config/initializers/aws_xray.rbRails.application.config.xray={# default segment name generated by XRay middlewarename: 'myrails',patch: %I[net_httpaws_sdk],# record db transactions as subsegmentsactive_record: true}Adding metadata/annotations using recorder
require'aws-xray-sdk'# Add annotations to the current active entityXRay.recorder.annotations[:k1]='v1'XRay.recorder.annotations.updatek2: 'v2',k3: 3# Add metadata to the current active entityXRay.recorder.metadata[:k1]='v1'# add to default namespaceXRay.recorder.metadata(namespace: :my_ns).updatek2: 'v2'XRay.recorder.sampled?doXRay.recorder.metadata.updatemy_meta# expensive metadata generation hereendCapture
require'aws-xray-sdk'XRay.recorder.capture('name_for_subsegment')do |subsegment|
resp=myfunc()subsegment.annotations.updatek1: 'v1'respend# Manually apply the parent segment for the captured subsegmentXRay.recorder.capture('name_for_subsegment',segment: my_segment)do |subsegment|
myfunc()endThread Injection
require'aws-xray-sdk'XRay.recorder.configure({patch: %I[net_http]})uri=URI.parse('http://aws.amazon.com/')# Get the active entity from current call contextentity=XRay.recorder.current_entityworkers=(0...3).mapdoThread.newdobegin# set X-Ray context for this threadXRay.recorder.inject_contextentitydohttp=Net::HTTP.new(uri.host,uri.port)http.request(Net::HTTP::Get.new(uri.request_uri))endrescueThreadErrorendendendworkers.map(&:join)Start a custom segment/subsegment
require'aws-xray-sdk'# Start a segmentsegment=XRay.recorder.begin_segment'my_service'# Start a subsegmentsubsegment=XRay.recorder.begin_subsegment'outbound_call',namespace: 'remote'# Add metadata or annotation here if necessarymy_annotations={k1: 'v1',k2: 1024}segment.annotations.updatemy_annotations# Add metadata to default namespacesubsegment.metadata[:k1]='v1'# Set user for the segment (subsegment is not supported)segment.user='my_name'# End segment/subsegmentXRay.recorder.end_subsegmentXRay.recorder.end_segmentThe AWS X-Ray SDK for Ruby is licensed under the Apache 2.0 License. See LICENSE and NOTICE for more information.