{"id":22989138,"url":"https://github.com/cookpad/aws-xray","last_synced_at":"2025-08-13T20:33:46.378Z","repository":{"id":21297862,"uuid":"92185247","full_name":"cookpad/aws-xray","owner":"cookpad","description":"The unofficial AWS X-Ray Tracing SDK for Ruby","archived":false,"fork":false,"pushed_at":"2023-03-17T01:42:56.000Z","size":284,"stargazers_count":50,"open_issues_count":0,"forks_count":16,"subscribers_count":3,"default_branch":"master","last_synced_at":"2025-08-09T19:57:47.776Z","etag":null,"topics":["aws","distributed-tracing","ruby","xray"],"latest_commit_sha":null,"homepage":null,"language":"Ruby","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/cookpad.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE.txt","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2017-05-23T14:53:40.000Z","updated_at":"2023-03-03T16:06:32.000Z","dependencies_parsed_at":"2024-06-19T22:48:41.142Z","dependency_job_id":"ec1f99cc-79f1-41f8-8c3a-dbf6cc16d36d","html_url":"https://github.com/cookpad/aws-xray","commit_stats":null,"previous_names":["taiki45/aws-xray"],"tags_count":72,"template":false,"template_full_name":null,"purl":"pkg:github/cookpad/aws-xray","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/cookpad%2Faws-xray","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/cookpad%2Faws-xray/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/cookpad%2Faws-xray/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/cookpad%2Faws-xray/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/cookpad","download_url":"https://codeload.github.com/cookpad/aws-xray/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/cookpad%2Faws-xray/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":270305842,"owners_count":24562109,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","status":"online","status_checked_at":"2025-08-13T02:00:09.904Z","response_time":66,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["aws","distributed-tracing","ruby","xray"],"created_at":"2024-12-15T04:16:33.474Z","updated_at":"2025-08-13T20:33:46.079Z","avatar_url":"https://github.com/cookpad.png","language":"Ruby","funding_links":[],"categories":[],"sub_categories":[],"readme":"# aws-xray\n[![Build Status](https://github.com/cookpad/aws-xray/actions/workflows/ci.yml/badge.svg?branch=master)](https://github.com/cookpad/aws-xray/actions/workflows/ci.yml)\n[![Gem Version](https://badge.fury.io/rb/aws-xray.svg)](https://badge.fury.io/rb/aws-xray)\n[![Coverage Status](https://coveralls.io/repos/github/taiki45/aws-xray/badge.svg)](https://coveralls.io/github/taiki45/aws-xray)\n[![Inline docs](http://inch-ci.org/github/taiki45/aws-xray.svg?branch=master)](http://inch-ci.org/github/taiki45/aws-xray)\n\nThe unofficial AWS X-Ray Tracing SDK for Ruby.\nIt enables you to capture in-coming HTTP requests and out-going HTTP requests and send them to X-Ray daemon automatically.\n\nAWS X-Ray is a distributed tracing system. See more detail about AWS X-Ray at [official document](http://docs.aws.amazon.com/xray/latest/devguide/aws-xray.html).\nIf you want to know what is distributed tracing, what is problems behind, etc.., please refer [Google's Dapper paper](https://research.google.com/pubs/pub36356.html).\n\n## Features\naws-xray has full features to build and send tracing data to AWS X-Ray.\n\n- Propagation support in both single and multi thread environments.\n- Instrumentation for major libraries.\n- Recording HTTP requests/responses and errors.\n- Annotation and metadata support.\n- Sampling.\n\n## Supported libraries\n- net/http\n- rack\n- faraday\n- rsolr\n\n## Getting started\n### Rails app\nJust require `aws/xray/rails`. It uses your application name as a service name by default. e.g. `Legacy::MyBlog` -\u003e `legacy-my-blog`.\n\n```ruby\n# Gemfile\ngem 'aws-xray', require: ['aws/xray/rails', 'aws/xray/hooks/net_http']\n```\n\nRequiring `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.\n\nThen setup [X-Ray daemon](http://docs.aws.amazon.com/xray/latest/devguide/xray-daemon.html) in your runtime environment.\nOnce the daemon is ready, run your application with some environment variables required by aws-xray gem.\n\n- `AWS_XRAY_LOCATION`: Point to X-Ray daemon's bind address and port. e.g. `localhost:2000`.\n- `AWS_XRAY_SAMPLING_RATE`: Set sampling rate. If you are just checking behavior, you can disable sampling by setting `1`.\n- `AWS_XRAY_EXCLUDED_PATHS`: Set your application's health check paths to avoid tracing health check requests.\n\nYou then see your application builds and sends tracing data to X-Ray daemon.\n\n## Configurations\n### Summary\nRecommend setting these operatinal concern via environment variables.\n\nName | Env var | Ruby interface\n-- | -- | --\nX-Ray daemon location | `AWS_XRAY_LOCATION` | `config.client_options`\nSampling rate | `AWS_XRAY_SAMPLING_RATE` | `config.sampling_rate`\nExcluded paths | `AWS_XRAY_EXCLUDED_PATHS` | `config.excluded_paths`\nApplication name | `AWS_XRAY_NAME` | `config.name`\n\nSee more configuration at [API documentation](http://www.rubydoc.info/gems/aws-xray/Aws/Xray/Configuration).\n\n### X-Ray daemon location\naws-xray does not send any trace data by default. Set `AWS_XRAY_LOCATION` environment variable like `AWS_XRAY_LOCATION=localhost:2000`.\n\nIn container environments, we run X-Ray daemon container beside application container.\nFor that case, pass `AWS_XRAY_LOCATION` environment variable to container to specify host and port of X-Ray daemon.\n\n```bash\ndocker run --link xray:xray --env AWS_XRAY_LOCATION=xray:2000 my-application\n```\n\n### Sampling\nSampling rate should be a float within 0 to 1. Both 0 and 1 are acceptable.\ne.g. 0 means never sampled, 1 means always sampled, 0.3 means 30% of requests (or traces in non-Rack app) will be sampled.\nThe default sampling rate is undefined so you should set your own sampling rate on production systems.\n\nSet sampling rate with `AWS_XRAY_SAMPLING_RATE` env var.\n\n### Excluded paths\nTo avoid tracing health checking requests, use \"excluded paths\" configuration.\n\n- Environment variable: `AWS_XRAY_EXCLUDED_PATHS=/health_check,/another_check`\n- Global configuration: `Aws::Xray.config.excluded_paths = ['/health_check', '/another_check', %r{/token/.+}]`\n\n### Recording application version\naws-xray automatically tries to set application version by reading `app_root/REVISION` file.\nIf you want to set another version, set it with:\n\n```ruby\n# In initialization phase.\nAws::Xray.config.version = 'deadbeef'\n```\n\n### Default annotation and metadata\naws-xray records hostname by default.\n\nIf you want to record specific annotation in all of your segments, configure like:\n\n```ruby\nAws::Xray.config.default_annotation = Aws::Xray.config.default_annotation.merge(key: 'value')\n```\n\nKeys must be alphanumeric characters with underscore and values must be one of String or Integer or Boolean values.\n\nFor metadata:\n\n```ruby\nAws::Xray.config.default_metadata = Aws::Xray.config.default_metadata.merge(key: ['some', 'meaningful', 'value'])\n```\n\nNote: See official document about annotation and metadata in AWS X-Ray.\n\n### Error handlers\nWhen aws-xray fails to send segments due to system call errors, it logs errors to stderr by default.\nIf you want to track these errors, for example with Sentry, you can configure your own error handler:\n\n```ruby\nAws::Xray.config.segment_sending_error_handler = MyCustomErrorHandler.new\n```\n\nThe error handler must be callable object and receive 2 arguments and 2 keyword arguments. See `Aws::Xray::DefaultErrorHandler` for more details.\n\nOptionally, aws-xray offers an error handler which integrates with Sentry. To use it:\n\n```ruby\nAws::Xray.config.segment_sending_error_handler = Aws::Xray::ErrorHandlerWithSentry.new\n```\n\n### Recording caller of HTTP requests\nSet `Aws::Xray.config.record_caller_of_http_requests = true` if you want to investigate the caller of specific HTTP requests.\nIt records caller of net/http and Faraday middleware.\n\n## Usage\n### Multi threaded environment\nTracing context is thread local. To pass current tracing context, copy current tracing context:\n\n```ruby\nThread.new(Aws::Xray.current_context.copy) do |context|\n  Aws::Xray.with_given_context(context) do\n    # Do something\n  end\nend\n```\n\n### Background jobs or offline processing\n```ruby\nrequire 'aws/xray'\nrequire 'aws/xray/hooks/net_http'\n\n# Start new tracing context then perform arbitrary actions in the block.\nAws::Xray.trace(name: 'my-app-batch') do |seg|\n  # Record out-going HTTP request/response with net/http hook.\n  Net::HTTP.get('example.com', '/index.html')\n\n  # Record arbitrary actions as subsegment.\n  Aws::Xray.start_subsegment(name: 'fetch-user', remote: true) do |sub|\n    # DB access or something to trace.\n  end\nend\n```\n\n### Rack middleware\n```ruby\n# config.ru\nrequire 'aws-xray'\nAws::Xray.config.name = 'my-app'\nuse Aws::Xray::Rack\n```\n\nThis enables your app to start tracing context.\n\n### Faraday middleware\n```ruby\nrequire 'aws/xray/faraday'\nFaraday.new('...', headers: { 'Host' =\u003e 'down-stream-app-id' } ) do |builder|\n  builder.use Aws::Xray::Faraday\n  # ...\nend\n```\n\nIf you don't use any Service Discovery tools, pass the down stream app name to the Faraday middleware:\n\n```ruby\nrequire 'aws/xray/faraday'\nFaraday.new('...') do |builder|\n  builder.use Aws::Xray::Faraday, 'down-stream-app-id'\n  # ...\nend\n```\n\n### Hooks\nYou can enable all the hooks with:\n\n```ruby\n# Gemfile\ngem 'aws-xray', require: 'aws/xray/hooks/all'\n```\n\n#### net/http hook\nTo monkey patch net/http and records out-going http requests automatically, just require `aws/xray/hooks/net_http`:\n\nIf you can pass headers for net/http client, you can setup subsegment name via `X-Aws-Xray-Name` header:\n\n```ruby\nNet::HTTP.start(host, port) do |http|\n  req = Net::HTTP::Get.new(uri, { 'X-Aws-Xray-Name' =\u003e 'target-app' })\n  http.request(req)\nend\n```\n\nIf you can't access headers, e.g. external client library like aws-sdk or dogapi-rb, setup subsegment name by `Aws::Xray.overwrite`:\n\n```ruby\nclient = Aws::Sns::Client.new\nresponse = Aws::Xray.overwrite(name: 'sns') do\n  client.create_topic(...)\nend\n```\n\n#### rsolr hook\nWhen 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.\n\nIf you want to give a specific name, configure it:\n\n```ruby\nAws::Xray.config.solr_hook_name = 'solr-development'\n```\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcookpad%2Faws-xray","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fcookpad%2Faws-xray","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcookpad%2Faws-xray/lists"}