aws-xray 0.34.0 → 0.34.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 7267a7fa4f024ff030f9d92c3fd1e140960c8f1c
-  data.tar.gz: 64347fabe77bb404f398cc66ba93547d8b68ec19
+  metadata.gz: 6211707f740b26f01a68faba9498a0d7424eff34
+  data.tar.gz: 8d52e3d25f2f259c6afab89ee63ea89bbdae8b58
 SHA512:
-  metadata.gz: 6ff9ccd3096e8eaeec4df15e1e83fdd4b5dd14054c73aab0dd34d110427816960164d643e48e54b8b54bbe7a55580ac5d282b283d17b0a7620c46a067db75312
-  data.tar.gz: a45c55edc853cfffc53362b0c8666a2c3691c5dc24e077ec9f1746af54be097d60fcc909bfc269f338111a22dfdfd3a1e5b44c869da9afb9d0819e3caa9b6c1b
+  metadata.gz: cff14025420e63287722a2066b72dbdf6858b6583d87643e4e833f4b4b0f32dedbb139937ae12bdd6534c667870e0e9ba02fc95a2e6a4993602211252d509718
+  data.tar.gz: 79230a1f4630fea2344a03391bd0cc5f55bfb5fb73b9cc5ae0088cb42fa5f18ee7b3ebe94138a4f6fbf9d89a7d5951f343fc451ae9833b979c17cbfa2ab79a73

data/CONTRIBUTING.md

@@ -0,0 +1,7 @@
+## Contributing
+Bug reports and pull requests are welcome on GitHub at https://github.com/taiki45/aws-xray.
+
+## Development
+After checking out the repo, run `bin/setup` to install dependencies. You can also run `bin/console` for an interactive prompt that will allow you to experiment. `rake` runs automated tests.
+
+To install this gem onto your local machine, run `bundle exec rake install`. To release a new version, update the version number in `version.rb`, and then run `bundle exec rake release`, which will create a git tag for the version, push git commits and tags, and push the `.gem` file to [rubygems.org](https://rubygems.org).

data/README.md

@@ -2,153 +2,68 @@
 [![Build Status](https://travis-ci.org/taiki45/aws-xray.svg?branch=master)](https://travis-ci.org/taiki45/aws-xray)
 [![Gem Version](https://badge.fury.io/rb/aws-xray.svg)](https://badge.fury.io/rb/aws-xray)
 [![Coverage Status](https://coveralls.io/repos/github/taiki45/aws-xray/badge.svg)](https://coveralls.io/github/taiki45/aws-xray)
+[![Inline docs](http://inch-ci.org/github/taiki45/aws-xray.svg?branch=master)](http://inch-ci.org/github/taiki45/aws-xray)
 
 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 xray-agent automatically.
+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 ditributed tracing system. See more detail about AWS X-Ray at [official document](http://docs.aws.amazon.com/xray/latest/devguide/aws-xray.html).
+AWS 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).
+If 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).
 
 ## Features
+aws-xray has full feautres to build and send tracing data to AWS X-Ray.
+
 - Propagatin support in both single and multi thread environment.
-- Rack middleware.
-- Faraday middleware.
-- net/http hook.
-- Tracing HTTP request/response.
-- Tracing errors.
+- Instrumentation for major libraries.
+- Recording HTTP request/response and errors.
 - Annotation and metadata support.
-- Sampling support.
-
-## Installation
-
-Add this line to your application's Gemfile:
-
-```ruby
-gem 'aws-xray'
-```
+- Sampling.
 
-And then execute:
+## Supported libraries
+- net/http
+- rack
+- faraday
+- activerecord
+- rsolr
 
-    $ bundle
-
-## Usage
+## Getting started
 ### Rails app
-Just require `aws/xray/rails`. It uses your application name by default.
-e.g. `Legacy::MyBlog` -> `legacy-my-blog`.
+Just require `aws/xray/rails`. It uses your application name by default. e.g. `Legacy::MyBlog` -> `legacy-my-blog`.
 
 ```ruby
 # Gemfile
-gem 'aws-xray', require: 'aws/xray/rails'
+gem 'aws-xray', require: ['aws/xray/rails', 'aws/xray/hooks/net_http']
 ```
 
-To trace out-going HTTP requests, see below.
+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.
 
-### Rack app
-```ruby
-# config.ru
-require 'aws-xray'
-Aws::Xray.config.name = 'my-app'
-use Aws::Xray::Rack
-```
+Then setup [X-Ray daemon](http://docs.aws.amazon.com/xray/latest/devguide/xray-daemon.html) in your runtime environment.
+Once the daemon is ready, run your application with some environment variable required by aws-xray gem.
 
-This allow your app to trace in-coming HTTP requests.
+- `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.
 
-To trace out-going HTTP requests, use Faraday middleware.
+You then see your application builds and sends tracing data to X-Ray daemon.
 
-```ruby
-require 'aws/xray/faraday'
-Faraday.new('...', headers: { 'Host' => 'down-stream-app-id' } ) do |builder|
-  builder.use Aws::Xray::Faraday
-  # ...
-end
-```
-
-If you don't use any Service Discovery tools, pass the down stream app name to the Faraday middleware:
-
-```ruby
-require 'aws/xray/faraday'
-Faraday.new('...') do |builder|
-  builder.use Aws::Xray::Faraday, 'down-stream-app-id'
-  # ...
-end
-```
-
-### non-Rack app (like background jobs)
-```ruby
-require 'aws-xray'
-
-# Build HTTP client with Faraday builder.
-# You can set the down stream app id to Host header as well.
-client = Faraday.new('...') do |builder|
-  builder.use Aws::Xray::Faraday, 'down-stream-app-id'
-  # ...
-end
-
-# Start new tracing context then perform arbitrary actions in the block.
-Aws::Xray.trace(name: 'my-app-batch') do |seg|
-  client.get('/foo')
-
-  Aws::Xray.start_subsegment(name: 'fetch-user', remote: true) do |sub|
-    # DB access or something to trace.
-  end
-end
-```
-
-### Hooks
-You can enable all the hooks with:
-
-```ruby
-# 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:
-
-```ruby
-Net::HTTP.start(host, port) do |http|
-  req = Net::HTTP::Get.new(uri, { 'X-Aws-Xray-Name' => 'target-app' })
-  http.request(req)
-end
-```
-
-If you can't access headers, e.g. external client library like aws-sdk or dogapi-rb, setup subsegment name by `Aws::Xray.overwrite`:
-
-```ruby
-client = Aws::Sns::Client.new
-response = Aws::Xray.overwrite(name: 'sns') do
-  client.create_topic(...)
-end
-```
-
-#### 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:
-
-```ruby
-Aws::Xray.config.solr_hook_name = 'solr-development'
-```
+## Configurations
+### Summary
+Recommend setting these operatinal concern via environment variables.
 
-### Multi threaded environment
-Tracing context is thread local. To pass current tracing context, copy current tracing context:
+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` | `config.name`
 
-```ruby
-Thread.new(Aws::Xray.current_context.copy) do |context|
-  Aws::Xray.with_given_context(context) do
-    # Do something
-  end
-end
-```
+See more configuration at [API documentation](http://www.rubydoc.info/gems/aws-xray/Aws/Xray/Configuration).
 
-## Configurations
-### X-Ray agent location
-aws-xray does not send any trace data by default. Set `AWS_XRAY_LOCATION` environment variable like `AWS_XRAY_LOCATION=localhost:2000`
-or set proper aws-agent location with configuration interface like `Aws::Xray.config.client_options = { host: "localhost", port: 2000 }`.
+### 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 often run xray agent container beside application container.
-For that case, pass `AWS_XRAY_LOCATION` environment variable to container to specify host and port of xray agent.
+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.
 
 ```bash
 docker run --link xray:xray --env AWS_XRAY_LOCATION=xray:2000 my-application
@@ -215,16 +130,103 @@ Aws::Xray.config.segment_sending_error_handler = Aws::Xray::ErrorHandlerWithSent
 Set `Aws::Xray.config.record_caller_of_http_requests = true` if you want investigate the caller of specific HTTP requests.
 It records caller of net/http and Faraday middleware.
 
-## Development
+## Usage
+### Multi threaded environment
+Tracing context is thread local. To pass current tracing context, copy current tracing context:
 
-After checking out the repo, run `bin/setup` to install dependencies. You can also run `bin/console` for an interactive prompt that will allow you to experiment.
+```ruby
+Thread.new(Aws::Xray.current_context.copy) do |context|
+  Aws::Xray.with_given_context(context) do
+    # Do something
+  end
+end
+```
 
-To install this gem onto your local machine, run `bundle exec rake install`. To release a new version, update the version number in `version.rb`, and then run `bundle exec rake release`, which will create a git tag for the version, push git commits and tags, and push the `.gem` file to [rubygems.org](https://rubygems.org).
+### Background jobs or offline processing
+```ruby
+require 'aws/xray'
+require 'aws/xray/hooks/net_http'
 
-## Contributing
+# 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('example.com', '/index.html')
 
-Bug reports and pull requests are welcome on GitHub at https://github.com/taiki45/aws-xray.
+  # Record arbitrary actions as subsegment.
+  Aws::Xray.start_subsegment(name: 'fetch-user', remote: true) do |sub|
+    # DB access or something to trace.
+  end
+end
+```
+
+### Rack middleware
+```ruby
+# config.ru
+require 'aws-xray'
+Aws::Xray.config.name = 'my-app'
+use Aws::Xray::Rack
+```
+
+This enables your app to start tracing context.
+
+### Faraday middleware
+```ruby
+require 'aws/xray/faraday'
+Faraday.new('...', headers: { 'Host' => 'down-stream-app-id' } ) do |builder|
+  builder.use Aws::Xray::Faraday
+  # ...
+end
+```
 
-## License
+If you don't use any Service Discovery tools, pass the down stream app name to the Faraday middleware:
 
-The gem is available as open source under the terms of the [MIT License](http://opensource.org/licenses/MIT).
+```ruby
+require 'aws/xray/faraday'
+Faraday.new('...') do |builder|
+  builder.use Aws::Xray::Faraday, 'down-stream-app-id'
+  # ...
+end
+```
+
+### Hooks
+You can enable all the hooks with:
+
+```ruby
+# 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:
+
+```ruby
+Net::HTTP.start(host, port) do |http|
+  req = Net::HTTP::Get.new(uri, { 'X-Aws-Xray-Name' => 'target-app' })
+  http.request(req)
+end
+```
+
+If you can't access headers, e.g. external client library like aws-sdk or dogapi-rb, setup subsegment name by `Aws::Xray.overwrite`:
+
+```ruby
+client = Aws::Sns::Client.new
+response = Aws::Xray.overwrite(name: 'sns') do
+  client.create_topic(...)
+end
+```
+
+#### activerecord hook
+`require 'aws/xray/hooks/active_record'`.
+
+Note this hook can record large amount of data.
+
+#### 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:
+
+```ruby
+Aws::Xray.config.solr_hook_name = 'solr-development'
+```

data/aws-xray.gemspec

@@ -33,6 +33,7 @@ Gem::Specification.new do |spec|
   spec.add_development_dependency 'rake'
   spec.add_development_dependency 'rsolr'
   spec.add_development_dependency 'rspec'
+  spec.add_development_dependency 'sentry-raven'
   spec.add_development_dependency 'simplecov'
   spec.add_development_dependency 'sqlite3'
   spec.add_development_dependency 'webmock'

data/lib/aws/xray.rb

@@ -23,6 +23,11 @@ module Aws
     Worker.reset(Worker::Configuration.new)
 
     class << self
+      # Start new tracing context and segment. If `trace` is given it start tracing context
+      # following given `trace`. If `name` is omitted, it uses global
+      # application name. Rescue all exceptions and record the exception to the
+      # segment. Then re-raise the exception.
+      #
       # @param [String] name a logical name of this tracing context.
       # @return [Object] result of given block
       def trace(name: nil, trace: Trace.generate)
@@ -34,11 +39,28 @@ module Aws
         end
       end
 
-      # @return [Boolean] whether tracing context is started or not.
+      # Start subsegment if current thread has tracing context then send the
+      # subsegment to X-Ray daemon. Rescue all exceptions and record the
+      # exception to the subsegment. Then re-raise the exception.
+      #
+      # @yield [Aws::Xray::Subsegment] null subsegment
+      # @return [Object] result of given block
+      def start_subsegment(name:, remote:, &block)
+        if started?
+          current_context.start_subsegment(name: name, remote: remote, &block)
+        else
+          block.call(Subsegment.build_null)
+        end
+      end
+
+      # Returns whether tracing context is started or not.
+      # @return [Boolean]
       def started?
         Context.started?
       end
 
+      # Return current tracing context set to current thread.
+      #
       # @return [Aws::Xray::Context]
       # @raise [Aws::Xray::NotSetError] when the current context is not yet set.
       #   Call this method after start tracing with `Aws::Xray.trace`.
@@ -46,22 +68,17 @@ module Aws
         Context.current
       end
 
+      # Set tracing context to current thread with given context object.
+      #
       # @param [Aws::Xray::Context] context copied context
       # @return [Object] result of given block
       def with_given_context(context, &block)
         Context.with_given_context(context, &block)
       end
 
-      # @yield [Aws::Xray::Subsegment] null subsegment
-      # @return [Object] result of given block
-      def start_subsegment(name:, remote:, &block)
-        if started?
-          current_context.start_subsegment(name: name, remote: remote, &block)
-        else
-          block.call(Subsegment.build_null)
-        end
-      end
-
+      # Temporary disabling tracing for given id in given block.
+      # CAUTION: the disabling will NOT be propagated between threads!!
+      #
       # @param [Symbol] id
       # @return [Object] result of given block
       def disable_trace(id, &block)
@@ -72,8 +89,18 @@ module Aws
         end
       end
 
-      # Overwrite under lying tracing name at once. If current context is not
-      # set to current thread, do nothing.
+      # Returns whether tracing is disabled with `.disable_trace` for given `id`.
+      # @param [Symbol] id
+      # @return [Boolean]
+      def disabled?(id)
+        started? && current_context.disabled?(id)
+      end
+
+      # Temporary overwrite subsegment with the name in the block. The
+      # overwriting will be occured only one time. If current context is not
+      # set to current thread, do nothing. CAUTION: the injection will NOT be
+      # propagated between threads!!
+      #
       # @param [String] name
       # @return [Object] result of given block
       def overwrite(name:, &block)

data/lib/aws/xray/context.rb

@@ -69,9 +69,7 @@ module Aws
         self.class.new(@name.dup, @trace.copy, @base_segment_id ? @base_segment_id.dup : nil)
       end
 
-      # Rescue all exceptions and record the exception to the segment.
-      # Then re-raise the exception.
-      #
+      # Use `Aws::Xray.trace` instead of this.
       # @yield [Aws::Xray::Segment]
       # @return [Object] A value which given block returns.
       def start_segment
@@ -90,6 +88,7 @@ module Aws
       end
       alias_method :base_trace, :start_segment
 
+      # Use `Aws::Xray.start_subsegment` instead of this.
       # @param [Boolean] remote
       # @param [String] name Arbitrary name of the sub segment. e.g. "funccall_f".
       # @yield [Aws::Xray::Subsegment]
@@ -110,9 +109,7 @@ module Aws
       end
       alias_method :child_trace, :start_subsegment
 
-      # Temporary disabling tracing for given id in given block.
-      # CAUTION: the disabling will NOT be propagated between threads!!
-      #
+      # Use `Aws::Xray.disable_trace` instead of this.
       # @param [Symbol] id must be unique between tracing methods.
       def disable_trace(id)
         @disabled_ids << id
@@ -124,15 +121,13 @@ module Aws
         end
       end
 
+      # Use `Aws::Xray.disabled?` instead of this.
+      # @param [Symbol] id
+      # @return [Boolean]
       def disabled?(id)
         @disabled_ids.include?(id)
       end
 
-      # CAUTION: the injection will NOT be propagated between threads!!
-      #
-      # Temporary overwrite subsegment with the name in the block. The
-      # overwriting will be occured only one time.
-      #
       # @param [String] name
       def overwrite(name:)
         return yield if @subsegment_name

data/lib/aws/xray/error_handlers.rb

@@ -26,11 +26,7 @@ Error: #{error}
       ERROR_LEVEL = 'warning'.freeze
 
       def call(error, payload, host:, port:)
-        if defined?(Raven)
-          ::Raven.capture_exception(error, level: ERROR_LEVEL, extra: { 'payload' => payload })
-        else
-          $stderr.puts('ErrorHandlerWithSentry is configured but `Raven` is undefined.')
-        end
+        ::Raven.capture_exception(error, level: ERROR_LEVEL, extra: { 'payload' => payload })
       end
     end
   end

data/lib/aws/xray/hooks/net_http.rb

@@ -27,7 +27,8 @@ module Aws
             req[TRACE_HEADER] = propagate_trace.to_header_value
             sub.set_http_request(request_record)
 
-            res = request_without_aws_xray(req, *args, &block)
+            # Don't record twice if down-steam caller calls Net::HTTP#request again.
+            res = Context.current.disable_trace(:net_http) { request_without_aws_xray(req, *args, &block) }
 
             sub.set_http_response_with_error(res.code.to_i, res['Content-Length'], remote: true)
             sub.add_metadata(CallerBuilder.call) if Aws::Xray.config.record_caller_of_http_requests

data/lib/aws/xray/version.rb

@@ -1,5 +1,5 @@
 module Aws
   module Xray
-    VERSION = '0.34.0'
+    VERSION = '0.34.1'
   end
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: aws-xray
 version: !ruby/object:Gem::Version
-  version: 0.34.0
+  version: 0.34.1
 platform: ruby
 authors:
 - Taiki Ono
 autorequire: 
 bindir: exe
 cert_chain: []
-date: 2017-07-04 00:00:00.000000000 Z
+date: 2017-07-10 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: rack
@@ -178,6 +178,20 @@ dependencies:
     - - ">="
       - !ruby/object:Gem::Version
         version: '0'
+- !ruby/object:Gem::Dependency
+  name: sentry-raven
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
 - !ruby/object:Gem::Dependency
   name: simplecov
   requirement: !ruby/object:Gem::Requirement
@@ -231,6 +245,7 @@ files:
 - ".rspec"
 - ".travis.yml"
 - CHANGELOG.md
+- CONTRIBUTING.md
 - Gemfile
 - LICENSE.txt
 - README.md
@@ -297,7 +312,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
       version: '0'
 requirements: []
 rubyforge_project: 
-rubygems_version: 2.5.2
+rubygems_version: 2.6.11
 signing_key: 
 specification_version: 4
 summary: The unofficial X-Ray Tracing SDK for Ruby.