Aws Xray

The unofficial AWS X-Ray Tracing SDK for Ruby
Alternatives To Aws Xray
Project NameStarsDownloadsRepos Using ThisPackages Using ThisMost Recent CommitTotal ReleasesLatest ReleaseOpen IssuesLicenseLanguage
Go Cloud8,91449922 days ago91August 03, 202220apache-2.0Go
The Go Cloud Development Kit (Go CDK): A library and tools for open cloud development in Go.
Aws Lambda Powertools Python1,983154 hours ago83July 04, 202287mit-0Python
A developer toolkit to implement Serverless best practices and increase developer velocity.
Aws Serverless Airline Booking1,936
21 days ago12mit-0Vue
Airline Booking is a sample web application that provides Flight Search, Flight Payment, Flight Booking and Loyalty points including end-to-end testing, GraphQL and CI/CD. This web application was the theme of Build on Serverless Season 2 on AWS Twitch running from April 24th until end of August in 2019.
Aws Xray Sdk Go259108a month ago52November 15, 202239apache-2.0Go
AWS X-Ray SDK for the Go programming language.
Aws Lambda Powertools Java22115 days ago32December 14, 202239mit-0Java
Powertools is a developer toolkit to implement Serverless best practices and increase developer velocity.
Java Specialagent153142 years ago34July 15, 202042apache-2.0Java
Automatic instrumentation for 3rd-party libraries in Java applications with OpenTracing.
Opentelemetry Ext Js1436a month ago57July 11, 202218apache-2.0TypeScript
js extensions for the open-telemetry project
Serverless Plugin Tracing11751425 years ago8October 13, 201710mitJavaScript
Enables AWS X-Ray tracing for Serverless
Pino Lambda85
3 months ago22April 26, 20222mitTypeScript
Send pino logs to cloudwatch with aws-lambda
Iopipe Python68
43 years ago64October 04, 20196apache-2.0Python
Python agent for AWS Lambda metrics, tracing, profiling & analytics
Alternatives To Aws Xray
Select To Compare

Alternative Project Comparisons


Build Status Gem Version Coverage Status Inline docs

The unofficial AWS X-Ray Tracing SDK for Ruby. It enables you to capture in-coming HTTP requests and out-going HTTP requests and send them to X-Ray daemon automatically.

AWS X-Ray is a distributed tracing system. See more detail about AWS X-Ray at official document. If you want to know what is distributed tracing, what is problems behind, etc.., please refer Google's Dapper paper.


aws-xray has full features to build and send tracing data to AWS X-Ray.

  • Propagation support in both single and multi thread environments.
  • Instrumentation for major libraries.
  • Recording HTTP requests/responses and errors.
  • Annotation and metadata support.
  • Sampling.

Supported libraries

  • net/http
  • rack
  • faraday
  • rsolr

Getting started

Rails app

Just require aws/xray/rails. It uses your application name as a service name by default. e.g. Legacy::MyBlog -> legacy-my-blog.

# Gemfile
gem 'aws-xray', require: ['aws/xray/rails', 'aws/xray/hooks/net_http']

Requiring aws/xray/rails inserts Rack middleware to the middleware stack and the middleware automatically starts tracing context. Another requiring aws/xray/hooks/net_http inserts a hook to net/http and it records out-going HTTP requests/responses automatically.

Then setup X-Ray daemon in your runtime environment. Once the daemon is ready, run your application with some environment variables required by aws-xray gem.

  • AWS_XRAY_LOCATION: Point to X-Ray daemon's bind address and port. e.g. localhost:2000.
  • AWS_XRAY_SAMPLING_RATE: Set sampling rate. If you are just checking behavior, you can disable sampling by setting 1.
  • AWS_XRAY_EXCLUDED_PATHS: Set your application's health check paths to avoid tracing health check requests.

You then see your application builds and sends tracing data to X-Ray daemon.



Recommend setting these operatinal concern via environment variables.

Name Env var Ruby interface
X-Ray daemon location AWS_XRAY_LOCATION config.client_options
Sampling rate AWS_XRAY_SAMPLING_RATE config.sampling_rate
Excluded paths AWS_XRAY_EXCLUDED_PATHS config.excluded_paths
Application name AWS_XRAY_NAME

See more configuration at API documentation.

X-Ray daemon location

aws-xray does not send any trace data by default. Set AWS_XRAY_LOCATION environment variable like AWS_XRAY_LOCATION=localhost:2000.

In container environments, we run X-Ray daemon container beside application container. For that case, pass AWS_XRAY_LOCATION environment variable to container to specify host and port of X-Ray daemon.

docker run --link xray:xray --env AWS_XRAY_LOCATION=xray:2000 my-application


Sampling rate should be a float within 0 to 1. Both 0 and 1 are acceptable. e.g. 0 means never sampled, 1 means always sampled, 0.3 means 30% of requests (or traces in non-Rack app) will be sampled. The default sampling rate is undefined so you should set your own sampling rate on production systems.

Set sampling rate with AWS_XRAY_SAMPLING_RATE env var.

Excluded paths

To avoid tracing health checking requests, use "excluded paths" configuration.

  • Environment variable: AWS_XRAY_EXCLUDED_PATHS=/health_check,/another_check
  • Global configuration: Aws::Xray.config.excluded_paths = ['/health_check', '/another_check', %r{/token/.+}]

Recording application version

aws-xray automatically tries to set application version by reading app_root/REVISION file. If you want to set another version, set it with:

# In initialization phase.
Aws::Xray.config.version = 'deadbeef'

Default annotation and metadata

aws-xray records hostname by default.

If you want to record specific annotation in all of your segments, configure like:

Aws::Xray.config.default_annotation = Aws::Xray.config.default_annotation.merge(key: 'value')

Keys must be alphanumeric characters with underscore and values must be one of String or Integer or Boolean values.

For metadata:

Aws::Xray.config.default_metadata = Aws::Xray.config.default_metadata.merge(key: ['some', 'meaningful', 'value'])

Note: See official document about annotation and metadata in AWS X-Ray.

Error handlers

When aws-xray fails to send segments due to system call errors, it logs errors to stderr by default. If you want to track these errors, for example with Sentry, you can configure your own error handler:

Aws::Xray.config.segment_sending_error_handler =

The error handler must be callable object and receive 2 arguments and 2 keyword arguments. See Aws::Xray::DefaultErrorHandler for more details.

Optionally, aws-xray offers an error handler which integrates with Sentry. To use it:

Aws::Xray.config.segment_sending_error_handler =

Recording caller of HTTP requests

Set Aws::Xray.config.record_caller_of_http_requests = true if you want to investigate the caller of specific HTTP requests. It records caller of net/http and Faraday middleware.


Multi threaded environment

Tracing context is thread local. To pass current tracing context, copy current tracing context: do |context|
  Aws::Xray.with_given_context(context) do
    # Do something

Background jobs or offline processing

require 'aws/xray'
require 'aws/xray/hooks/net_http'

# Start new tracing context then perform arbitrary actions in the block.
Aws::Xray.trace(name: 'my-app-batch') do |seg|
  # Record out-going HTTP request/response with net/http hook.
  Net::HTTP.get('', '/index.html')

  # Record arbitrary actions as subsegment.
  Aws::Xray.start_subsegment(name: 'fetch-user', remote: true) do |sub|
    # DB access or something to trace.

Rack middleware

require 'aws-xray' = 'my-app'
use Aws::Xray::Rack

This enables your app to start tracing context.

Faraday middleware

require 'aws/xray/faraday''...', headers: { 'Host' => 'down-stream-app-id' } ) do |builder|
  builder.use Aws::Xray::Faraday
  # ...

If you don't use any Service Discovery tools, pass the down stream app name to the Faraday middleware:

require 'aws/xray/faraday''...') do |builder|
  builder.use Aws::Xray::Faraday, 'down-stream-app-id'
  # ...


You can enable all the hooks with:

# Gemfile
gem 'aws-xray', require: 'aws/xray/hooks/all'

net/http hook

To monkey patch net/http and records out-going http requests automatically, just require aws/xray/hooks/net_http:

If you can pass headers for net/http client, you can setup subsegment name via X-Aws-Xray-Name header:

Net::HTTP.start(host, port) do |http|
  req =, { 'X-Aws-Xray-Name' => 'target-app' })

If you can't access headers, e.g. external client library like aws-sdk or dogapi-rb, setup subsegment name by Aws::Xray.overwrite:

client =
response = Aws::Xray.overwrite(name: 'sns') do

rsolr hook

When you want to name solr requests, use this hook by require aws/xray/hooks/rsolr. The typical usecase is you use local haproxy to proxy to solr instances and you want to distinguish these requests from other reqeusts using local haproxy.

If you want to give a specific name, configure it:

Aws::Xray.config.solr_hook_name = 'solr-development'
Popular Tracing Projects
Popular Amazon Web Services Projects
Popular Operations Categories
Related Searches

Get A Weekly Email With Trending Projects For These Categories
No Spam. Unsubscribe easily at any time.
Amazon Web Services
Http Requests
Distributed Tracing