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_http aws_sdk]
}
XRay.recorder.configure(user_config)Working with Rails
# Edit Gemfile to add XRay middleware
gem 'aws-xray-sdk', require: ['aws-xray-sdk/facets/rails/railtie']
# Configure the recorder in app_root/config/initializers/aws_xray.rb
Rails.application.config.xray = {
# default segment name generated by XRay middleware
name: 'myrails',
patch: %I[net_http aws_sdk],
# record db transactions as subsegments
active_record: true
}Adding metadata/annotations using recorder
require 'aws-xray-sdk'
# Add annotations to the current active entity
XRay.recorder.annotations[:k1] = 'v1'
XRay.recorder.annotations.update k2: 'v2', k3: 3
# Add metadata to the current active entity
XRay.recorder.metadata[:k1] = 'v1' # add to default namespace
XRay.recorder.metadata(namespace: :my_ns).update k2: 'v2'
XRay.recorder.sampled? do
XRay.recorder.metadata.update my_meta # expensive metadata generation here
endCapture
require 'aws-xray-sdk'
XRay.recorder.capture('name_for_subsegment') do |subsegment|
resp = myfunc()
subsegment.annotations.update k1: 'v1'
resp
end
# Manually apply the parent segment for the captured subsegment
XRay.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 context
entity = XRay.recorder.current_entity
workers = (0...3).map do
Thread.new do
begin
# set X-Ray context for this thread
XRay.recorder.inject_context entity do
http = Net::HTTP.new(uri.host, uri.port)
http.request(Net::HTTP::Get.new(uri.request_uri))
end
rescue ThreadError
end
end
end
workers.map(&:join)Start a custom segment/subsegment
require 'aws-xray-sdk'
# Start a segment
segment = XRay.recorder.begin_segment 'my_service'
# Start a subsegment
subsegment = XRay.recorder.begin_subsegment 'outbound_call', namespace: 'remote'
# Add metadata or annotation here if necessary
my_annotations = {
k1: 'v1',
k2: 1024
}
segment.annotations.update my_annotations
# Add metadata to default namespace
subsegment.metadata[:k1] = 'v1'
# Set user for the segment (subsegment is not supported)
segment.user = 'my_name'
# End segment/subsegment
XRay.recorder.end_subsegment
XRay.recorder.end_segmentThe AWS X-Ray SDK for Ruby is licensed under the Apache 2.0 License. See LICENSE and NOTICE for more information.
React
Typescript
Django
Laravel
Facebook
Microsoft
Google
Alibaba
D3
Tencent