initial commit

Author: haotianw465

.gitignore

@@ -0,0 +1,16 @@
+*.gem
+*.rbc
+
+.bundle
+.config
+.coverage
+.yardoc
+Gemfile.lock
+
+doc/
+pkg/
+
+tmp
+test/tmp
+coverage
+vendor/

.yardopts

@@ -0,0 +1,5 @@
+--title 'AWS X-Ray SDK for Ruby'
+--markup markdown
+--markup-provider rdiscount
+--no-progress
+- LICENSE

Gemfile

@@ -0,0 +1,3 @@
+source 'https://rubygems.org'
+
+gemspec

LICENSE

@@ -1,4 +1,3 @@
-
                                  Apache License
                            Version 2.0, January 2004
                         http://www.apache.org/licenses/

NOTICE

@@ -1,2 +1,3 @@
-AWS Xray SDK Ruby
-Copyright 2017 Amazon.com, Inc. or its affiliates. All Rights Reserved. 
+AWS X-Ray SDK for Ruby
+Copyright 2017 Amazon.com, Inc. or its affiliates. All Rights Reserved.
+

README.md

@@ -1,5 +1,189 @@
-AWS Xray SDK Ruby
+# AWS X-Ray SDK for Ruby <sup><sup><sup>(beta)</sup></sup></sup>
+
+![Screenshot of the AWS X-Ray console](/images/example_servicemap.png?raw=true)
+
+## Installing
+
+The AWS X-Ray SDK for Ruby is compatible with Ruby 2.3.6 and newer Ruby versions.
+
+To install the Ruby gem for your project, add it to your project Gemfile.
+
+```
+# Gemfile
+gem 'aws-xray-sdk'
+```
+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](https://forums.aws.amazon.com/forum.jspa?forumID=241&start=0).
+* Open a support ticket with [AWS Support](http://docs.aws.amazon.com/awssupport/latest/user/getting-started.html).
+* If you think you may have found a bug, open an [issue](https://github.com/aws/aws-xray-sdk-ruby/issues/new).
+
+## 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](https://github.com/aws/aws-xray-sdk-ruby/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](https://github.com/aws/aws-xray-sdk-ruby#getting-help) section. Keeping the list of open issues lean helps us respond in a timely manner.
+
+## Documentation
+
+The [developer guide](https://docs.aws.amazon.com/xray/latest/devguide) provides in-depth guidance about using the AWS X-Ray service.
+The [API Reference](http://docs.aws.amazon.com/xray-sdk-for-ruby/latest/reference/) provides documentation for public APIs of all classes in the SDK.
+
+## Quick Start
+
+**Configuration**
+
+```ruby
+require 'aws-xray-sdk'
+
+# configure path based sampling rules in case of web app
+my_sampling_rules = {
+  version: 1,
+  rules: [
+    {
+      description: 'healthcheck',
+      service_name: '*',
+      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**
+
+```ruby
+# 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**
+
+```ruby
+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**
+
+```ruby
+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**
+
+```ruby
+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**
+
+```ruby
+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
 
-This library is licensed under the Apache 2.0 License. 
+The AWS X-Ray SDK for Ruby is licensed under the Apache 2.0 License. See LICENSE and NOTICE for more information.

Rakefile

@@ -0,0 +1,23 @@
+require 'bundler/gem_tasks'
+
+Rake::Task['release'].clear
+
+# default task
+task default: %i[yard test]
+
+require 'rake'
+require 'rake/testtask'
+require 'yard'
+
+# tasks
+desc 'execute all tests'
+Rake::TestTask.new :test do |t|
+  t.test_files = FileList['test/**/tc_*.rb']
+  t.verbose = false
+  t.warning = false
+end
+
+desc 'generate API reference documentation'
+YARD::Rake::YardocTask.new :yard do |t|
+  t.files = ['lib/**/*.rb']
+end

aws-xray-sdk.gemspec

@@ -0,0 +1,31 @@
+lib = File.expand_path('../lib', __FILE__)
+$LOAD_PATH.unshift(lib) unless $LOAD_PATH.include?(lib)
+require 'aws-xray-sdk/version'
+
+Gem::Specification.new do |spec|
+  spec.name          = 'aws-xray-sdk'
+  spec.version       = XRay::VERSION
+  spec.author        = 'Amazon Web Services'
+  spec.email         = '[email protected]'
+  spec.summary       = 'AWS X-Ray SDK for Ruby'
+  spec.description   = 'The AWS X-Ray SDK for Ruby enables Ruby developers to record and emit information from within their applications to the AWS X-Ray service.'
+  spec.homepage      = 'https://github.com/aws/aws-xray-sdk-ruby'
+  spec.license       = 'Apache-2.0'
+
+  spec.files         = Dir.glob('lib/**/*')
+  spec.executables   = spec.files.grep(%r{^bin/}) { |f| File.basename(f) }
+  spec.test_files    = spec.files.grep(%r{^(test|spec|features)/})
+  spec.require_paths = ['lib']
+
+  spec.add_dependency 'oj', '~> 3.0'
+
+  spec.add_development_dependency 'aws-sdk-dynamodb', '~> 1'
+  spec.add_development_dependency 'aws-sdk-s3', '~> 1'
+  spec.add_development_dependency 'bundler', '~> 1.0'
+  spec.add_development_dependency 'minitest', '~> 5.0'
+  spec.add_development_dependency 'rake', '~> 12.0'
+  spec.add_development_dependency 'rdiscount', '~> 2.2'
+  spec.add_development_dependency 'simplecov', '~> 0.15'
+  spec.add_development_dependency 'webmock', '~> 3.0'
+  spec.add_development_dependency 'yard', '~> 0.9'
+end

images/example_servicemap.png

@@ -0,0 +1,10 @@
+require 'aws-xray-sdk/recorder'
+
+module XRay
+  @recorder = Recorder.new
+
+  # providing the default global recorder
+  def self.recorder
+    @recorder
+  end
+end