aws-xray-sdk 0.9.0

data/lib/aws-xray-sdk/sampling/default_sampler.rb

@@ -0,0 +1,105 @@
+require 'aws-xray-sdk/sampling/sampler'
+require 'aws-xray-sdk/sampling/sampling_rule'
+require 'aws-xray-sdk/exceptions'
+
+module XRay
+  # The default sampler that uses internally defined
+  # sampling rule and reservoir models to decide sampling decision.
+  # It also uses the default sampling rule.
+  # An example definition:
+  #   {
+  #     version: 1,
+  #     rules: [
+  #       {
+  #         description: 'Player moves.',
+  #         service_name: '*',
+  #         http_method: '*',
+  #         url_path: '/api/move/*',
+  #         fixed_target: 0,
+  #         rate: 0.05
+  #       }
+  #     ],
+  #     default: {
+  #       fixed_target: 1,
+  #       rate: 0.1
+  #     }
+  #   }
+  # This example defines one custom rule and a default rule.
+  # The custom rule applies a five-percent sampling rate with no minimum
+  # number of requests to trace for paths under /api/move/. The default
+  # rule traces the first request each second and 10 percent of additional requests.
+  # The SDK applies custom rules in the order in which they are defined.
+  # If a request matches multiple custom rules, the SDK applies only the first rule.
+  class DefaultSampler
+    include Sampler
+    DEFAULT_RULES = {
+      version: 1,
+      default: {
+        fixed_target: 1,
+        rate: 0.05
+      },
+      rules: []
+    }.freeze
+
+    def initialize
+      load_sampling_rules(DEFAULT_RULES)
+    end
+
+    # Return True if the sampler decide to sample based on input
+    # information and sampling rules. It will first check if any
+    # custom rule should be applied, if not it falls back to the
+    # default sampling rule.
+    # All arugments are extracted from incoming requests by
+    # X-Ray middleware to perform path based sampling.
+    def sample_request?(service_name:, url_path:, http_method:)
+      # directly fallback to non-path-based if all arguments are nil
+      return sample? unless service_name || url_path || http_method
+      @custom_rules ||= []
+      @custom_rules.each do |c|
+        return should_sample?(c) if c.applies?(target_name: service_name, target_path: url_path, target_method: http_method)
+      end
+      sample?
+    end
+
+    # Decides if should sample based on non-path-based rule.
+    # Currently only the default rule is not path-based.
+    def sample?
+      should_sample?(@default_rule)
+    end
+
+    # @param [Hash] v The sampling rules definition.
+    def sampling_rules=(v)
+      load_sampling_rules(v)
+    end
+
+    # @return [Array] An array of [SamplingRule]
+    def sampling_rules
+      all_rules = []
+      all_rules << @default_rule
+      all_rules << @custom_rules unless @custom_rules.empty?
+      all_rules
+    end
+
+    private
+
+    def should_sample?(rule)
+      return true if rule.reservoir.take
+      Random.rand <= rule.rate
+    end
+
+    def load_sampling_rules(v)
+      version = v[:version]
+      if version != 1
+        raise InvalidSamplingConfigError, %('Sampling rule version #{version} is not supported.')
+      end
+      unless v[:default]
+        raise InvalidSamplingConfigError, 'A default rule must be provided.'
+      end
+      @default_rule = SamplingRule.new rule_definition: v[:default], default: true
+      @custom_rules = []
+      v[:rules].each do |d|
+        @custom_rules << SamplingRule.new(rule_definition: d)
+      end
+    end
+  end
+end

data/lib/aws-xray-sdk/sampling/reservoir.rb

@@ -0,0 +1,35 @@
+module XRay
+  # Keeps track of the number of sampled segments within
+  # a single second. This class is implemented to be
+  # thread-safe to achieve accurate sampling.
+  class Reservoir
+    # @param [Integer] traces_per_sec The number of guranteed sampled
+    #   segments per second.
+    def initialize(traces_per_sec: 0)
+      @traces_per_sec = traces_per_sec
+      @used_this_sec = 0
+      @this_sec = Time.now.to_i
+      @lock = Mutex.new
+    end
+
+    # Returns `true` if there are segments left within the
+    # current second, otherwise returns `false`.
+    def take
+      # nothing to provide if reserved is set to 0
+      return false if @traces_per_sec.zero?
+      @lock.synchronize do
+        now = Time.now.to_i
+        # refresh time frame
+        if now != @this_sec
+          @used_this_sec = 0
+          @this_sec = now
+        end
+        # return false if reserved item ran out
+        return false unless @used_this_sec < @traces_per_sec
+        # otherwise increment used counter and return true
+        @used_this_sec += 1
+        return true
+      end
+    end
+  end
+end

data/lib/aws-xray-sdk/sampling/sampler.rb

@@ -0,0 +1,27 @@
+module XRay
+  # The sampler interface that calculates if a segment
+  # should be sampled or not upon creation based on the
+  # sampling rules it holds. It doesn't respect sampling decision
+  # from upstream.
+  module Sampler
+    # Decides if a segment should be sampled for an incoming request.
+    # Used in case of middleware.
+    def sample_request?(service_name:, url_path:, http_method:)
+      raise 'Not implemented'
+    end
+
+    # Decides if a segment should be sampled merely based on internal
+    # sampling rules.
+    def sample?
+      raise 'Not implemented'
+    end
+
+    def sampling_rules=(v)
+      raise 'Not implemented'
+    end
+
+    def sampling_rules
+      raise 'Not implemented'
+    end
+  end
+end

data/lib/aws-xray-sdk/sampling/sampling_rule.rb

@@ -0,0 +1,57 @@
+require 'aws-xray-sdk/exceptions'
+require 'aws-xray-sdk/sampling/reservoir'
+require 'aws-xray-sdk/search_pattern'
+
+module XRay
+  # One SamplingRule object represents one rule defined from the rules hash definition.
+  # It can be either a custom rule or the default rule.
+  class SamplingRule
+    attr_reader :fixed_target, :rate, :service_name,
+                :method, :path, :reservoir, :default
+
+    # @param [Hash] rule_definition Hash that defines a single rule.
+    # @param default A boolean flag indicates if this rule is the default rule.
+    def initialize(rule_definition:, default: false)
+      @fixed_target = rule_definition[:fixed_target]
+      @rate = rule_definition[:rate]
+
+      @service_name = rule_definition[:service_name]
+      @method = rule_definition[:http_method]
+      @path = rule_definition[:url_path]
+
+      @default = default
+      validate
+      @reservoir = Reservoir.new traces_per_sec: @fixed_target
+    end
+
+    # Determines whether or not this sampling rule applies to
+    # the incoming request based on some of the request's parameters.
+    # Any None parameters provided will be considered an implicit match.
+    def applies?(target_name:, target_path:, target_method:)
+      name_match   = !target_name   || SearchPattern.wildcard_match?(pattern: @service_name, text: target_name)
+      path_match   = !target_path   || SearchPattern.wildcard_match?(pattern: @path, text: target_path)
+      method_match = !target_method || SearchPattern.wildcard_match?(pattern: @method, text: target_method)
+      name_match && path_match && method_match
+    end
+
+    private
+
+    def validate
+      if @fixed_target < 0 || @rate < 0
+        raise InvalidSamplingConfigError, 'All rules must have non-negative values for fixed_target and rate.'
+      end
+
+      if @default
+        # validate default rule
+        if @service_name || @method || @path
+          raise InvalidSamplingConfigError, 'The default rule must not specify values for url_path, service_name, or http_method.'
+        end
+      else
+        # validate custom rule
+        unless @service_name && @method && @path
+          raise InvalidSamplingConfigError, 'All non-default rules must have values for url_path, service_name, and http_method.'
+        end
+      end
+    end
+  end
+end

data/lib/aws-xray-sdk/search_pattern.rb

@@ -0,0 +1,82 @@
+module XRay
+  # custom pattern matching for performance and the SDK use cases.
+  module SearchPattern
+    # Performs a case-insensitive wildcard match against two strings.
+    # This method works with pseduo-regex chars; specifically ? and * are supported.
+    # An asterisk (*) represents any combination of characters.
+    # A question mark (?) represents any single character.
+    # @param [String] pattern The regex-like pattern to be compared against.
+    # @param [String] text The string to compare against the pattern.
+    # @param case_insensitive A boolean flag. Default is true.
+    def self.wildcard_match?(pattern:, text:, case_insensitive: true)
+      return false unless pattern && text
+      pattern_len = pattern.length
+      text_len = text.length
+      return text_len.zero? if pattern_len.zero?
+      # Check the special case of a single * pattern, as it's common
+      return true if pattern == '*'
+
+      if case_insensitive
+        # do not mutate original input
+        pattern = pattern.downcase
+        text = text.downcase
+      end
+      # Infix globs are relatively rare, and the below search is expensive.
+      # Check for infix globs and, in their absence, do the simple thing.
+      if !pattern.include?('*') || pattern.index('*') == pattern_len - 1
+        return simple_wildcard_match? pattern: pattern, text: text
+      end
+
+      # The res[i] is used to record if there is a match between
+      # the first i chars in text and the first j chars in pattern.
+      # So will return res[textLength+1] in the end
+      # Loop from the beginning of the pattern
+      # case not '*': if text[i]==pattern[j] or pattern[j] is '?',
+      # and res[i] is true, set res[i+1] to true, otherwise false.
+      # case '*': since '*' can match any globing, as long as there is a true
+      # in res before i, all the res[i+1], res[i+2],...,res[textLength]
+      # could be true
+      res = Array.new(text_len + 1)
+      res[0] = true
+      (0...pattern_len).each do |j|
+        p = pattern[j]
+        if p != '*'
+          (text_len - 1).downto(0) do |i|
+            res[i + 1] = res[i] && (p == '?' || (p == text[i]))
+          end
+        else
+          i = 0
+          i += 1 while i <= text_len && !res[i]
+          (i..text_len + 1).each do |m|
+            res[m] = true
+          end
+        end
+        res[0] = res[0] && (p == '*')
+      end
+      res[text_len]
+    end
+
+    private_class_method
+
+    def self.simple_wildcard_match?(pattern:, text:)
+      j = 0
+      pattern_len = pattern.length
+      text_len = text.length
+      (0...pattern_len).each do |i|
+        p = pattern[i]
+        # Presumption for this method is that globs only occur at end
+        return true if p == '*'
+        if p == '?'
+          # No character to match
+          return false if j == text_len
+        else
+          return false if j >= text_len || p != text[j]
+        end
+        j += 1
+      end
+      # Ate up all the pattern and didn't end at a glob, so a match
+      # will have consumed all the text
+      j == text_len
+    end
+  end
+end

data/lib/aws-xray-sdk/segment_naming/dynamic_naming.rb

@@ -0,0 +1,26 @@
+require 'aws-xray-sdk/segment_naming/segment_naming'
+require 'aws-xray-sdk/search_pattern'
+
+module XRay
+  # Decides what name to use on a segment generated from an incoming request.
+  # This default naming takes the host name and compares it to a pre-defined pattern.
+  # If the host name matches that pattern, it returns the host name, otherwise
+  # it returns the fallback name. The host name usually comes from the incoming
+  # request's headers.
+  class DynamicNaming
+    include SegmentNaming
+
+    # @param [String] fallback The fallback name used when there is no match
+    #   between host name and specified pattern.
+    def initialize(fallback:)
+      @fallback = fallback
+    end
+
+    # @param [String] host The host name fetched from the incoming request's header.
+    def provide_name(host:)
+      # use fallback name when either the pattern or host name is unavailable.
+      return fallback unless pattern && !pattern.empty? && host && !host.empty?
+      SearchPattern.wildcard_match?(pattern: pattern, text: host) ? host : fallback
+    end
+  end
+end

data/lib/aws-xray-sdk/segment_naming/segment_naming.rb

@@ -0,0 +1,10 @@
+module XRay
+  # The interface that provides the segment name
+  # based on host name, pattern and the fallback name.
+  module SegmentNaming
+    attr_accessor :fallback, :pattern
+    def provide_name(host:)
+      raise 'Not implemented'
+    end
+  end
+end

data/lib/aws-xray-sdk/streaming/default_streamer.rb

@@ -0,0 +1,53 @@
+require 'aws-xray-sdk/streaming/streamer'
+require 'aws-xray-sdk/logger'
+
+module XRay
+  # The default streamer use subsegment count as the threshold
+  # for performance reasons and it streams out subtrees
+  # where all the nodes in it are completed.
+  class DefaultStreamer
+    include Streamer
+    include Logging
+
+    def initialize
+      @stream_threshold = 50
+    end
+
+    # @param [Segment] segment Check if the provided segment exceeds
+    #   the threshold to stream.
+    def eligible?(segment:)
+      # only get subsegments to stream from sampled segments.
+      segment && segment.sampled && segment.subsegment_size >= stream_threshold
+    end
+
+    # @param [Segment] root The target segment to stream subsegments from.
+    # @param [Emitter] emitter The emitter employed to send data to the daemon.
+    def stream_subsegments(root:, emitter:)
+      children = root.subsegments
+      children_ready = []
+
+      unless children.empty?
+        # Collect ready subtrees from root.
+        children.each do |child|
+          children_ready << child if stream_subsegments root: child, emitter: emitter
+        end
+      end
+
+      # If this subtree is ready, go back to the root's parent
+      # to try to find a bigger subtree
+      return true if children_ready.length == children.length && root.closed?
+      # Otherwise this subtree has at least one non-ready node.
+      # Only stream its ready child subtrees.
+      children_ready.each do |child|
+        root.remove_subsegment subsegment: child
+        emitter.send_entity entity: child
+      end
+      # Return false so this node won't be added to its parent's ready children.
+      false
+    end
+
+    # @return [Integer] The maximum number of subsegments a segment
+    #   can hold before streaming.
+    attr_accessor :stream_threshold
+  end
+end

data/lib/aws-xray-sdk/streaming/streamer.rb

@@ -0,0 +1,17 @@
+module XRay
+  # The interface used by the X-Ray recoder to get eligible subsegments
+  # to be streamed out from a given segment.
+  module Streamer
+    def eligible?(segment:)
+      raise 'Not implemented'
+    end
+
+    def subsegments_to_stream(segment:, emitter:, force: false)
+      raise 'Not implemented'
+    end
+
+    def stream_threshold=(v)
+      raise 'Not implemented'
+    end
+  end
+end

data/lib/aws-xray-sdk/version.rb

@@ -0,0 +1,3 @@
+module XRay
+  VERSION = '0.9.0'
+end

metadata

@@ -0,0 +1,224 @@
+--- !ruby/object:Gem::Specification
+name: aws-xray-sdk
+version: !ruby/object:Gem::Version
+  version: 0.9.0
+platform: ruby
+authors:
+- Amazon Web Services
+autorequire: 
+bindir: bin
+cert_chain: []
+date: 2018-01-09 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: oj
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.0'
+- !ruby/object:Gem::Dependency
+  name: aws-sdk-dynamodb
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1'
+- !ruby/object:Gem::Dependency
+  name: aws-sdk-s3
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1'
+- !ruby/object:Gem::Dependency
+  name: bundler
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.0'
+- !ruby/object:Gem::Dependency
+  name: minitest
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '5.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '5.0'
+- !ruby/object:Gem::Dependency
+  name: rake
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '12.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '12.0'
+- !ruby/object:Gem::Dependency
+  name: rdiscount
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.2'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.2'
+- !ruby/object:Gem::Dependency
+  name: simplecov
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.15'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.15'
+- !ruby/object:Gem::Dependency
+  name: webmock
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.0'
+- !ruby/object:Gem::Dependency
+  name: yard
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.9'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.9'
+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.
+email: aws-xray-ruby@amazon.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- lib/aws-xray-sdk.rb
+- lib/aws-xray-sdk/configuration.rb
+- lib/aws-xray-sdk/context/context.rb
+- lib/aws-xray-sdk/context/default_context.rb
+- lib/aws-xray-sdk/emitter/default_emitter.rb
+- lib/aws-xray-sdk/emitter/emitter.rb
+- lib/aws-xray-sdk/exceptions.rb
+- lib/aws-xray-sdk/facets/aws_sdk.rb
+- lib/aws-xray-sdk/facets/helper.rb
+- lib/aws-xray-sdk/facets/net_http.rb
+- lib/aws-xray-sdk/facets/rack.rb
+- lib/aws-xray-sdk/facets/rails/active_record.rb
+- lib/aws-xray-sdk/facets/rails/ex_middleware.rb
+- lib/aws-xray-sdk/facets/rails/railtie.rb
+- lib/aws-xray-sdk/facets/resources/aws_params_whitelist.rb
+- lib/aws-xray-sdk/facets/resources/aws_services_whitelist.rb
+- lib/aws-xray-sdk/logger.rb
+- lib/aws-xray-sdk/model/annotations.rb
+- lib/aws-xray-sdk/model/cause.rb
+- lib/aws-xray-sdk/model/dummy_entities.rb
+- lib/aws-xray-sdk/model/entity.rb
+- lib/aws-xray-sdk/model/metadata.rb
+- lib/aws-xray-sdk/model/segment.rb
+- lib/aws-xray-sdk/model/subsegment.rb
+- lib/aws-xray-sdk/model/trace_header.rb
+- lib/aws-xray-sdk/patcher.rb
+- lib/aws-xray-sdk/plugins/ec2.rb
+- lib/aws-xray-sdk/plugins/ecs.rb
+- lib/aws-xray-sdk/plugins/elastic_beanstalk.rb
+- lib/aws-xray-sdk/recorder.rb
+- lib/aws-xray-sdk/sampling/default_sampler.rb
+- lib/aws-xray-sdk/sampling/reservoir.rb
+- lib/aws-xray-sdk/sampling/sampler.rb
+- lib/aws-xray-sdk/sampling/sampling_rule.rb
+- lib/aws-xray-sdk/search_pattern.rb
+- lib/aws-xray-sdk/segment_naming/dynamic_naming.rb
+- lib/aws-xray-sdk/segment_naming/segment_naming.rb
+- lib/aws-xray-sdk/streaming/default_streamer.rb
+- lib/aws-xray-sdk/streaming/streamer.rb
+- lib/aws-xray-sdk/version.rb
+homepage: https://github.com/aws/aws-xray-sdk-ruby
+licenses:
+- Apache-2.0
+metadata: {}
+post_install_message: 
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubyforge_project: 
+rubygems_version: 2.7.3
+signing_key: 
+specification_version: 4
+summary: AWS X-Ray SDK for Ruby
+test_files: []