aws-xray-sdk 0.9.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 78007efa0d29f0f16fa12ee0437cb6214a64c7d43d6cd1bde7ca9286d44d110b
+  data.tar.gz: e9fe587611d3f346b98e632ab88772769246d351b06ce46cc42f015fb15899e2
+SHA512:
+  metadata.gz: bb2ed43b514b1b50278c370c32b159f8f58bed0cd3e105b91f9ff0afb74a6ba66f184f515a294c2520cca7ad9b102506534f58fd4f3a778daeec02688900b437
+  data.tar.gz: 5ce0c0474f40d316dfa1ec0eddc13d156886c93b211bebd7963ae795c7b1eeca72fbc696d3a0bb948d3ad8ad106eab60d1b0774602217a794c2f92f42bac2938

data/lib/aws-xray-sdk.rb

@@ -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

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

@@ -0,0 +1,158 @@
+require 'aws-xray-sdk/exceptions'
+require 'aws-xray-sdk/patcher'
+require 'aws-xray-sdk/emitter/default_emitter'
+require 'aws-xray-sdk/context/default_context'
+require 'aws-xray-sdk/sampling/default_sampler'
+require 'aws-xray-sdk/streaming/default_streamer'
+require 'aws-xray-sdk/segment_naming/dynamic_naming'
+require 'aws-xray-sdk/plugins/ec2'
+require 'aws-xray-sdk/plugins/ecs'
+require 'aws-xray-sdk/plugins/elastic_beanstalk'
+require 'aws-xray-sdk/logger'
+
+module XRay
+  # This class stores all configurations for X-Ray recorder
+  # and should be initialized only once.
+  class Configuration
+    include Patcher
+
+    SEGMENT_NAME_KEY = 'AWS_XRAY_TRACING_NAME'.freeze
+    CONFIG_KEY = %I[logger name sampling plugins daemon_address segment_naming
+                    naming_pattern emitter streamer context context_missing
+                    sampling_rules stream_threshold patch].freeze
+
+    def initialize
+      @name = ENV[SEGMENT_NAME_KEY]
+      @sampling = true
+      @emitter = DefaultEmitter.new
+      @context = DefaultContext.new
+      @sampler = DefaultSampler.new
+      @streamer = DefaultStreamer.new
+      @segment_naming = DynamicNaming.new fallback: @name
+      @plugins = []
+    end
+
+    # @param [String] v The default segment name.
+    #   Environment vairable takes higher precedence.
+    def name=(v)
+      @name = ENV[SEGMENT_NAME_KEY] || v
+    end
+
+    # proxy method to the emitter's daemon_address config.
+    def daemon_address=(v)
+      emitter.daemon_address = v
+    end
+
+    # proxy method to the context's context_missing config.
+    def context_missing=(v)
+      context.context_missing = v
+    end
+
+    # proxy method to the sampler's sampling rule config.
+    def sampling_rules=(v)
+      sampler.sampling_rules = v
+    end
+
+    # proxy method to the streamer's stream threshold config.
+    def stream_threshold=(v)
+      streamer.stream_threshold = v
+    end
+
+    # proxy method to the dynamic naming's pattern config.
+    def naming_pattern=(v)
+      segment_naming.pattern = v
+    end
+
+    # makes a sampling decision based on internal configure, e.g.
+    #   if sampling enabled and the default sampling rule.
+    def sample?
+      return true unless sampling
+      sampler.sample?
+    end
+
+    # @param [Hash] user_config The user configuration overrides.
+    def configure(user_config)
+      raise InvalidConfigurationError.new('User config must be a Hash.') unless user_config.is_a?(Hash)
+      return if user_config.empty?
+
+      user_config.each_key do |key|
+        case key
+        when :logger
+          XRay::Logging.logger = user_config[key]
+        when :name
+          self.name = user_config[key]
+        when :context
+          self.context = user_config[key]
+        when :context_missing
+          self.context_missing = user_config[key]
+        when :sampler
+          self.sampler = user_config[key]
+        when :sampling_rules
+          self.sampling_rules = user_config[key]
+        when :sampling
+          self.sampling = user_config[key]
+        when :emitter
+          self.emitter = user_config[key]
+        when :daemon_address
+          self.daemon_address = user_config[key]
+        when :segment_naming
+          self.segment_naming = user_config[key]
+        when :naming_pattern
+          self.naming_pattern = user_config[key]
+        when :streamer
+          self.streamer = user_config[key]
+        when :stream_threshold
+          self.stream_threshold = user_config[key]
+        when :plugins
+          self.plugins = load_plugins(user_config[key])
+        when :patch
+          patch(user_config[key])
+        else
+          raise InvalidConfigurationError.new(%(Invalid config key #{key}.))
+        end
+      end
+    end
+
+    attr_accessor :emitter
+
+    attr_accessor :context
+
+    attr_accessor :sampler
+
+    attr_accessor :streamer
+
+    attr_accessor :segment_naming
+
+    attr_accessor :plugins
+
+    attr_accessor :sampling
+
+    # @return [String] The default segment name.
+    attr_reader :name
+
+    # The global logger used across the X-Ray SDK.
+    # @return [Logger]
+    attr_reader :logger
+
+    private
+
+    def load_plugins(symbols)
+      plugins = []
+      symbols.each do |symbol|
+        case symbol
+        when :ec2
+          plugins << XRay::Plugins::EC2
+        when :ecs
+          plugins << XRay::Plugins::ECS
+        when :elastic_beanstalk
+          plugins << XRay::Plugins::ElasticBeanstalk
+        else
+          raise InvalidConfigurationError.new(%(Unsupported plugin #{symbol}.))
+        end
+      end
+      # eager loads aws metadata to eliminate impact on first incoming request
+      plugins.each(&:aws)
+      plugins
+    end
+  end
+end

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

@@ -0,0 +1,26 @@
+module XRay
+  # The interface of context management for the X-Ray recorder.
+  module Context
+    # @param [Entity] entity The entity to be stored in the context.
+    def store_entity(entity:)
+      raise 'Not implemented'
+    end
+
+    def current_entity
+      raise 'Not implemented'
+    end
+
+    def clear!
+      raise 'Not implemented'
+    end
+
+    # Put current active entity to the new context storage.
+    def inject_context(entity, target_ctx: nil)
+      raise 'Not implemented'
+    end
+
+    def handle_context_missing
+      raise 'Not implemented'
+    end
+  end
+end

data/lib/aws-xray-sdk/context/default_context.rb

@@ -0,0 +1,81 @@
+require 'aws-xray-sdk/logger'
+require 'aws-xray-sdk/context/context'
+require 'aws-xray-sdk/exceptions'
+
+module XRay
+  # The default context storage management used by
+  # the X-Ray recorder. It uses thread local to store
+  # segments and subsegments.
+  class DefaultContext
+    include Context
+    include Logging
+
+    LOCAL_KEY = '_aws_xray_entity'.freeze
+    CONTEXT_MISSING_KEY = 'AWS_XRAY_CONTEXT_MISSING'.freeze
+    SUPPORTED_STRATEGY = %w[RUNTIME_ERROR LOG_ERROR].freeze
+    DEFAULT_STRATEGY = SUPPORTED_STRATEGY[0]
+
+    attr_reader :context_missing
+
+    def initialize
+      strategy = ENV[CONTEXT_MISSING_KEY] || DEFAULT_STRATEGY
+      @context_missing = sanitize_strategy(strategy)
+    end
+
+    # @param [Entity] entity The entity to be stored in the context.
+    def store_entity(entity:)
+      Thread.current[LOCAL_KEY] = entity
+    end
+
+    # @return [Entity] The current active entity(could be segment or subsegment).
+    def current_entity
+      if entity = Thread.current[LOCAL_KEY]
+        entity
+      else
+        handle_context_missing
+      end
+    end
+
+    # Clear the current thread local storage on X-Ray related entities.
+    def clear!
+      Thread.current[LOCAL_KEY] = nil
+    end
+
+    # @param [Entity] entity The entity to inject.
+    # @param [Thread] target_ctx Put the provided entity to the new thread.
+    def inject_context(entity, target_ctx: nil)
+      target_ctx ||= Thread.current
+      target_ctx[LOCAL_KEY] = entity if entity
+    end
+
+    # When the current entity needs to be accessed but there is none,
+    # it handles the missing context based on the configuration.
+    # On `RUNTIME_ERROR` it raises `ContextMissingError`.
+    # On 'LOG_ERROR' it logs an error message and return `nil`.
+    def handle_context_missing
+      case context_missing
+      when 'RUNTIME_ERROR'
+        raise ContextMissingError
+      when 'LOG_ERROR'
+        logger.error %(can not find the current context.)
+      end
+      nil
+    end
+
+    def context_missing=(v)
+      strategy = ENV[CONTEXT_MISSING_KEY] || v
+      @context_missing = sanitize_strategy(strategy)
+    end
+
+    private
+
+    def sanitize_strategy(v)
+      if SUPPORTED_STRATEGY.include?(v)
+        v
+      else
+        logger.warn %(context missing #{v} is not supported, switch to default #{DEFAULT_STRATEGY}.)
+        DEFAULT_STRATEGY
+      end
+    end
+  end
+end

data/lib/aws-xray-sdk/emitter/default_emitter.rb

@@ -0,0 +1,53 @@
+require 'socket'
+require 'aws-xray-sdk/logger'
+require 'aws-xray-sdk/emitter/emitter'
+require 'aws-xray-sdk/exceptions'
+
+module XRay
+  # The default emitter the X-Ray recorder uses to send segments/subsegments
+  # to the X-Ray daemon over UDP using a non-blocking socket.
+  class DefaultEmitter
+    include Emitter
+    include Logging
+
+    attr_reader :address
+
+    def initialize
+      @socket = UDPSocket.new
+      @address = ENV[DAEMON_ADDRESS_KEY] || '127.0.0.1:2000'
+      configure_socket(@address)
+    end
+
+    # Serializes a segment/subsegment and sends it to the X-Ray daemon
+    # over UDP. It is no-op for non-sampled entity.
+    # @param [Entity] entity The entity to send
+    def send_entity(entity:)
+      return nil unless entity.sampled
+      begin
+        payload = %(#{@@protocol_header}#{@@protocol_delimiter}#{entity.to_json})
+        logger.debug %(sending payload #{payload} to daemon at #{address}.)
+        @socket.send payload, 0
+      rescue StandardError => e
+        logger.warn %(failed to send payload due to #{e.message})
+      end
+    end
+
+    def daemon_address=(v)
+      v = ENV[DAEMON_ADDRESS_KEY] || v
+      @address = v
+      configure_socket(v)
+    end
+
+    private
+
+    def configure_socket(v)
+      begin
+        addr = v.split(':')
+        host, ip = addr[0], addr[1].to_i
+        @socket.connect(host, ip)
+      rescue StandardError
+        raise InvalidDaemonAddressError, %(Invalid X-Ray daemon address specified: #{v}.)
+      end
+    end
+  end
+end

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

@@ -0,0 +1,24 @@
+require 'json'
+
+module XRay
+  # The emitter interface the X-Ray recorder uses to send segments/subsegments
+  # to the X-Ray daemon over UDP.
+  module Emitter
+    DAEMON_ADDRESS_KEY = 'AWS_XRAY_DAEMON_ADDRESS'.freeze
+
+    @@protocol_header = {
+      format:   'json',
+      version:  1
+    }.to_json
+    @@protocol_delimiter = "\n"
+
+    # @param [Entity] entity Entity to send.
+    def send_entity(entity:)
+      raise 'Not implemented'
+    end
+
+    def daemon_address=(v)
+      raise 'Not implemented'
+    end
+  end
+end

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

@@ -0,0 +1,31 @@
+module XRay
+  # All custom exception thrown by the SDK should subclass AwsXRayError.
+  class AwsXRaySdkError < ::StandardError; end
+
+  class EntityClosedError < AwsXRaySdkError
+    def initialize
+      super('Segment or subsegment already ended.')
+    end
+  end
+
+  class ContextMissingError < AwsXRaySdkError
+    def initialize
+      super('Can not find any active segment or subsegment.')
+    end
+  end
+
+  class SegmentNameMissingError < AwsXRaySdkError
+  end
+
+  class InvalidDaemonAddressError < AwsXRaySdkError
+  end
+
+  class InvalidSamplingConfigError < AwsXRaySdkError
+  end
+
+  class InvalidConfigurationError < AwsXRaySdkError
+  end
+
+  class UnsupportedPatchingTargetError < AwsXRaySdkError
+  end
+end

data/lib/aws-xray-sdk/facets/aws_sdk.rb

@@ -0,0 +1,127 @@
+require 'aws-sdk-core'
+require 'aws-xray-sdk/facets/helper'
+require 'aws-xray-sdk/facets/resources/aws_params_whitelist'
+require 'aws-xray-sdk/facets/resources/aws_services_whitelist'
+
+module XRay
+  class AwsSDKPlugin < Seahorse::Client::Plugin
+    option :xray_recorder, default: XRay.recorder
+
+    def add_handlers(handlers, config)
+      # run before Seahorse::Client::Plugin::ParamValidator (priority 50)
+      handlers.add Handler, step: :validate, priority: 49
+    end
+
+    # Handler to capture AWS API calls as subsegments
+    class Handler < Seahorse::Client::Handler
+      include XRay::Facets::Helper
+
+      def call(context)
+        recorder = Aws.config[:xray_recorder]
+        operation = context.operation_name
+        service_name = context.client.class.api.metadata['serviceAbbreviation'] ||
+                       context.client.class.to_s.split('::')[1]
+        recorder.capture service_name, namespace: 'aws' do |subsegment|
+          # inject header string before calling downstream AWS services
+          context.http_request.headers[TRACE_HEADER] = prep_header_str entity: subsegment
+          response = @handler.call(context)
+          http_response = context.http_response
+          resp_meta = {
+            status: http_response.status_code,
+            content_length: http_response.headers['content-length'].to_i
+          }
+          aws = {
+            # XRay back-end right now has strict operation name matching
+            operation: sanitize_op_name(operation),
+            region: context.client.config.region,
+            retries: context.retries,
+            request_id: http_response.headers['x-amzn-requestid']
+          }
+          # S3 returns special request id in response headers
+          if service_name == 'S3'
+            aws[:id_2] = http_response.headers['x-amz-id-2']
+          end
+
+          operation_h = AwsParams.whitelist[:services]
+                                 .fetch(service_name.to_sym, {})
+                                 .fetch(:operations, {})[operation]
+          unless operation_h.nil?
+            params_capture req_params: context.params, resp_params: response.to_h,
+                           capture: operation_h, meta: aws
+          end
+          subsegment.aws = aws
+          if err = response.error
+            subsegment.add_exception exception: err, remote: true
+          end
+          subsegment.merge_http_response response: resp_meta
+          response
+        end
+      end
+
+      private
+
+      def inject_headers(request:, entity:)
+        request.headers[TRACE_HEADER] = prep_header_str entity: entity
+      end
+
+      def sanitize_op_name(opname)
+        opname.to_s.split('_').collect(&:capitalize).join if opname
+      end
+
+      def params_capture(req_params:, resp_params:, capture:, meta:)
+        if norm = capture[:request_parameters]
+          capture_normal params: req_params, capture: norm, meta: meta
+        end
+
+        if norm = capture[:response_parameters]
+          capture_normal params: resp_params, capture: norm, meta: meta
+        end
+
+        if spec = capture[:request_descriptors]
+          capture_special params: req_params, capture: spec, meta: meta
+        end
+
+        if spec = capture[:response_descriptors]
+          capture_special params: resp_params, capture: spec, meta: meta
+        end
+      end
+
+      def capture_normal(params:, capture:, meta:)
+        params.each_key do |key|
+          meta[key] = params[key] if capture.include?(key)
+        end
+      end
+
+      def capture_special(params:, capture:, meta:)
+        params.each_key do |key|
+          process_descriptor(target: params[key], descriptor: capture[key], meta: meta) if capture.include?(key)
+        end
+      end
+
+      def process_descriptor(target:, descriptor:, meta:)
+        # "get_count" = true
+        v = target.length if descriptor[:get_count]
+        # "get_keys" = true
+        v = target.keys if descriptor[:get_keys]
+        meta[descriptor[:rename_to]] = v
+      end
+    end
+  end
+
+  # Add X-Ray plugin to AWS SDK clients
+  module AwsSDKPatcher
+    def self.patch(services: nil, recorder: XRay.recorder)
+      force = services.nil?
+      services ||= AwsServices.whitelist
+      services.each do |s|
+        begin
+          Aws.const_get(%(#{s}::Client)).add_plugin XRay::AwsSDKPlugin
+          Aws.config.update xray_recorder: recorder
+        rescue NameError
+          # swallow the error if no explicit user config
+          raise unless force
+        end
+      end
+    end
+  end
+end