📣 OpenTelemetry Ruby with AWS X-Ray

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.

AWS X-Ray SDK for Ruby (beta)

Installing

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.

Getting Help

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.

Opening Issues

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.

Documentation

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.

Quick Start

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 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 instrumented

See also lib/aws-xray-sdk/lambda.rb

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
end

Capture

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()
end

Thread 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_segment

License

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

aws-xray-sdk

Development

Runtime