aws-xray-sdk 0.9.0

data/lib/aws-xray-sdk/model/metadata.rb

@@ -0,0 +1,77 @@
+require 'oj'
+require 'aws-xray-sdk/exceptions'
+
+module XRay
+  # Metadata are key-value pairs with values of any type, including objects
+  # and lists, but that are not indexed. Use metadata to record data
+  # you want to store in the trace but don't need to use for searching traces.
+  class Metadata
+    def initialize(entity)
+      @data = {}
+      @entity = entity
+    end
+
+    def sub_meta(namespace)
+      @data[namespace] = SubMeta.new(@entity) unless @data[namespace]
+      @data[namespace]
+    end
+
+    def to_h
+      @data
+    end
+  end
+
+  # The actual class that stores all data under a certain namespace.
+  class SubMeta
+    def initialize(entity)
+      @data = {}
+      @entity = entity
+    end
+
+    def [](key)
+      @data[key]
+    end
+
+    def []=(k, v)
+      raise EntityClosedError if @entity.closed?
+      @data[k] = v
+    end
+
+    def update(h)
+      raise EntityClosedError if @entity.closed?
+      @data.merge!(h)
+    end
+
+    def to_h
+      @data
+    end
+
+    def to_json
+      @to_json ||= begin
+        Oj.dump to_h, mode: :compat, use_as_json: true
+      end
+    end
+  end
+
+  # Singleton facade metadata class doing no-op for performance
+  # in case of not sampled X-Ray entities.
+  module FacadeMetadata
+    class << self
+      def [](key)
+        # no-op
+      end
+
+      def []=(k, v)
+        # no-op
+      end
+
+      def update(h)
+        # no-op
+      end
+
+      def to_h
+        # no-op
+      end
+    end
+  end
+end

data/lib/aws-xray-sdk/model/segment.rb

@@ -0,0 +1,63 @@
+require 'aws-xray-sdk/model/entity'
+
+module XRay
+  # The compute resources running your application logic send data
+  # about their work as segments. A segment provides the resource's name,
+  # details about the request, and details about the work done.
+  class Segment
+    include Entity
+    attr_accessor :ref_counter, :subsegment_size, :origin, :user
+
+    # @param [String] trace_id Manually crafted trace id.
+    # @param [String] name Must be specified either on object creation or
+    #   on environment variable `AWS_TRACING_NAME`. The latter has higher precedence.
+    # @param [String] parent_id ID of the segment/subsegment representing the upstream caller.
+    def initialize(trace_id: nil, name: nil, parent_id: nil)
+      @trace_id = trace_id
+      @name = ENV['AWS_TRACING_NAME'] || name
+      @parent_id = parent_id
+      @start_time = Time.now.to_f
+      @ref_counter = 0
+      @subsegment_size = 0
+      @sampled = true
+    end
+
+    def trace_id
+      @trace_id ||= begin
+        %[1-#{Time.now.to_i.to_s(16)}-#{SecureRandom.hex(12)}]
+      end
+    end
+
+    def add_subsegment(subsegment:)
+      super subsegment: subsegment
+      @ref_counter += 1
+      @subsegment_size += 1
+    end
+
+    def remove_subsegment(subsegment:)
+      super subsegment: subsegment
+      @subsegment_size = subsegment_size - subsegment.all_children_count - 1
+    end
+
+    def decrement_ref_counter
+      @ref_counter -= 1
+    end
+
+    def ready_to_send?
+      closed? && ref_counter.zero?
+    end
+
+    def to_h
+      h = super
+      h[:trace_id] = trace_id
+      h[:origin] = origin if origin
+      h[:parent_id] = @parent_id if @parent_id
+      h[:user] = user if user
+      h
+    end
+
+    def segment
+      self
+    end
+  end
+end

data/lib/aws-xray-sdk/model/subsegment.rb

@@ -0,0 +1,67 @@
+require 'aws-xray-sdk/model/entity'
+
+module XRay
+  # The work done in a single segment can be broke down into subsegments.
+  # Subsegments provide more granular timing information and details about
+  # downstream calls that your application made to fulfill the original request.
+  # A subsegment can contain additional details about a call to an AWS service,
+  # an external HTTP API, or an SQL database.
+  class Subsegment
+    include Entity
+
+    attr_reader :segment
+    attr_accessor :sql
+
+    # @param [String] name The subsegment name.
+    # @param [Segment] segment The root parent segment. This segment
+    #   may not be its direct parent.
+    # @param [String] namespace Currently supported namespaces are
+    #   'remote', 'aws', 'local'.
+    def initialize(name:, segment:, namespace: 'local')
+      @name = name
+      @segment = segment
+      @namespace = namespace
+      @start_time = Time.now.to_f
+      @sampled = true
+    end
+
+    def add_subsegment(subsegment:)
+      super subsegment: subsegment
+      segment.ref_counter += 1
+      segment.subsegment_size += 1
+    end
+
+    def remove_subsegment(subsegment:)
+      super subsegment: subsegment
+      cur = segment.subsegment_size
+      segment.subsegment_size = cur - subsegment.all_children_count - 1
+    end
+
+    def close(end_time: nil)
+      super end_time: end_time
+      segment.decrement_ref_counter
+    end
+
+    def sql
+      @sql ||= {}
+    end
+
+    # Returns the number of its direct and indirect children.
+    # This is useful when we remove the reference to a subsegment
+    # and need to keep remaining subsegment size accurate.
+    def all_children_count
+      size = subsegments.count
+      subsegments.each { |v| size += v.all_children_count }
+      size
+    end
+
+    def to_h
+      h = super
+      h[:trace_id] = segment.trace_id
+      h[:sql] = sql unless sql.empty?
+      h[:type] = 'subsegment'
+      h[:namespace] = namespace if namespace
+      h
+    end
+  end
+end

data/lib/aws-xray-sdk/model/trace_header.rb

@@ -0,0 +1,54 @@
+require 'aws-xray-sdk/logger'
+
+module XRay
+  # The sampling decision and trace ID are added to HTTP requests in
+  # tracing headers named ``X-Amzn-Trace-Id``. The first X-Ray-integrated
+  # service that the request hits adds a tracing header, which is read
+  # by the X-Ray SDK and included in the response.
+  class TraceHeader
+    include Logging
+    attr_accessor :root, :parent_id, :sampled
+
+    # @param [String] root Trace id.
+    # @param [String] parent_id The id of the parent segment or subsegment.
+    # @param [Integer] sampled 0 means not sampled.
+    def initialize(root:, parent_id:, sampled:)
+      @root = root
+      @parent_id = parent_id
+      @sampled = sampled.to_i if sampled
+    end
+
+    def self.from_header_string(header_str:)
+      empty_header if header_str.to_s.empty?
+      header = header_str.delete(' ').downcase
+      tmp = {}
+      begin
+        fields = header.split(';')
+        fields.each do |f|
+          pair = f.split('=')
+          tmp[pair[0].to_sym] = pair[1]
+        end
+        new root: tmp[:root], parent_id: tmp[:parent], sampled: tmp[:sampled]
+      rescue StandardError
+        logger.warn %(Invalid trace header #{header}. Ignored.)
+        empty_header
+      end
+    end
+
+    # @return [String] The heading string constructed based on this header object.
+    def header_string
+      return '' unless root
+      if !parent_id
+        %(Root=#{root};Sampled=#{sampled})
+      elsif !sampled
+        %(Root=#{root};Parent=#{parent_id})
+      else
+        %(Root=#{root};Parent=#{parent_id};Sampled=#{sampled})
+      end
+    end
+
+    def self.empty_header
+      new root: nil, parent_id: nil, sampled: nil
+    end
+  end
+end

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

@@ -0,0 +1,21 @@
+require 'aws-xray-sdk/exceptions'
+
+module XRay
+  # Patching external libraries/frameworks to be traced by X-Ray recorder.
+  module Patcher
+    # @param [Array] targets A list of libraries/frameworks to patch.
+    def patch(targets)
+      targets.each do |l|
+        case l
+        when :net_http
+          require 'aws-xray-sdk/facets/net_http'
+        when :aws_sdk
+          require 'aws-xray-sdk/facets/aws_sdk'
+          XRay::AwsSDKPatcher.patch
+        else
+          raise UnsupportedPatchingTargetError.new(%(#{l} is not supported by X-Ray SDK.))
+        end
+      end
+    end
+  end
+end

data/lib/aws-xray-sdk/plugins/ec2.rb

@@ -0,0 +1,39 @@
+require 'open-uri'
+require 'aws-xray-sdk/logger'
+
+module XRay
+  module Plugins
+    # A plugin that gets the EC2 instance-id and AZ if running on an EC2 instance.
+    module EC2
+      include Logging
+
+      ORIGIN = 'AWS::EC2::Instance'.freeze
+      # http://docs.aws.amazon.com/AWSEC2/latest/UserGuide/ec2-instance-metadata.html#instancedata-data-retrieval
+      ID_ADDR = 'http://169.254.169.254/latest/meta-data/instance-id'.freeze
+      AZ_ADDR = 'http://169.254.169.254/latest/meta-data/placement/availability-zone'.freeze
+
+      def self.aws
+        @@aws ||= begin
+          instance_id = open(ID_ADDR, open_timeout: 1).read
+          az = open(AZ_ADDR, open_timeout: 1).read
+          {
+            ec2: {
+              instance_id: instance_id,
+              availability_zone: az
+            }
+          }
+        rescue StandardError => e
+          # Two attempts in total to get EC2 metadata
+          @retries ||= 0
+          if @retries < 1
+            @retries += 1
+            retry
+          else
+            @@aws = {}
+            Logging.logger.warn %(can not get the ec2 instance metadata due to: #{e.message}.)
+          end
+        end
+      end
+    end
+  end
+end

data/lib/aws-xray-sdk/plugins/ecs.rb

@@ -0,0 +1,23 @@
+require 'socket'
+require 'aws-xray-sdk/logger'
+
+module XRay
+  module Plugins
+    # Due to lack of ECS container metadata service, the only host information
+    # available is the host name.
+    module ECS
+      include Logging
+
+      ORIGIN = 'AWS::ECS::Container'.freeze
+
+      def self.aws
+        @@aws ||= begin
+          { ecs: { container: Socket.gethostname } }
+        rescue StandardError => e
+          @@aws = {}
+          Logging.logger.warn %(can not get the ecs container hostname due to: #{e.message}.)
+        end
+      end
+    end
+  end
+end

data/lib/aws-xray-sdk/plugins/elastic_beanstalk.rb

@@ -0,0 +1,25 @@
+require 'oj'
+require 'aws-xray-sdk/logger'
+
+module XRay
+  module Plugins
+    # A plugin that records information about the elastic beanstalk environment
+    # hosting your application.
+    module ElasticBeanstalk
+      include Logging
+
+      CONF_PATH = '/var/elasticbeanstalk/xray/environment.conf'.freeze
+      ORIGIN = 'AWS::ElasticBeanstalk::Environment'.freeze
+
+      def self.aws
+        @@aws ||= begin
+          file = File.open(CONF_PATH)
+          { elastic_beanstalk: Oj.load(file) }
+        rescue StandardError => e
+          @@aws = {}
+          Logging.logger.warn %(can not get the environment config due to: #{e.message}.)
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,209 @@
+require 'aws-xray-sdk/configuration'
+require 'aws-xray-sdk/exceptions'
+require 'aws-xray-sdk/model/segment'
+require 'aws-xray-sdk/model/subsegment'
+require 'aws-xray-sdk/model/dummy_entities'
+require 'aws-xray-sdk/model/annotations'
+require 'aws-xray-sdk/model/metadata'
+
+module XRay
+  # A global AWS X-Ray recorder that will begin/end segments/subsegments
+  # and send them to the X-Ray daemon. It is also responsible for managing
+  # context.
+  class Recorder
+    attr_reader :config
+
+    def initialize(user_config: nil)
+      @config = Configuration.new
+      @config.configure(user_config) unless user_config.nil?
+    end
+
+    # Begin a segment for the current context. The recorder
+    # only keeps one segment at a time. Create a second one without
+    # closing existing one will overwrite the existing one.
+    # @return [Segment] thew newly created segment.
+    def begin_segment(name, trace_id: nil, parent_id: nil, sampled: nil)
+      seg_name = name || config.name
+      raise SegmentNameMissingError if seg_name.to_s.empty?
+
+      # sampling decision comes from outside has higher precedence.
+      sample = sampled.nil? ? config.sample? : sampled
+      if sample
+        segment = Segment.new name: seg_name, trace_id: trace_id, parent_id: parent_id
+        populate_runtime_context(segment)
+      else
+        segment = DummySegment.new name: seg_name, trace_id: trace_id, parent_id: parent_id
+      end
+      context.store_entity entity: segment
+      segment
+    end
+
+    # @return [Segment] the active segment tied to the current context.
+    #   If the current context is under a subsegment, it returns its parent segment.
+    def current_segment
+      entity = current_entity
+      entity.segment if entity
+    end
+
+    # End the current segment and send it to X-Ray daemon if it is ready.
+    def end_segment(end_time: nil)
+      segment = current_segment
+      return unless segment
+      segment.close end_time: end_time
+      context.clear!
+      emitter.send_entity entity: segment if segment.ready_to_send?
+    end
+
+    # Begin a new subsegment and add it to be the child of the current active
+    # subsegment or segment. Also tie the new created subsegment to the current context.
+    # Its sampling decision will follow its parent.
+    # @return [Subsegment] the newly created subsegment.
+    def begin_subsegment(name, namespace: nil, segment: nil)
+      entity = segment || current_entity
+      return unless entity
+      if entity.sampled
+        subsegment = Subsegment.new name: name, segment: entity.segment, namespace: namespace
+      else
+        subsegment = DummySubsegment.new name: name, segment: entity.segment
+      end
+      # attach the new created subsegment under the current active entity
+      entity.add_subsegment subsegment: subsegment
+      # associate the new subsegment to the current context
+      context.store_entity entity: subsegment
+      subsegment
+    end
+
+    # @return [Subsegment] the active subsegment tied to the current context.
+    #   Returns nil if the current context has no associated subsegment.
+    def current_subsegment
+      entity = context.current_entity
+      entity.is_a?(Subsegment) ? entity : nil
+    end
+
+    # End the current active subsegment. It also send the entire segment if
+    # this subsegment is the last one open or stream out subsegments of its
+    # parent segment if the stream threshold is breached.
+    def end_subsegment(end_time: nil)
+      entity = current_entity
+      return unless entity.is_a?(Subsegment)
+      entity.close end_time: end_time
+      # update current context
+      if entity.parent.closed?
+        context.clear!
+      else
+        context.store_entity entity: entity.parent
+      end
+      # check if the entire segment can be send.
+      # If not, stream subsegments when threshold is reached.
+      segment = entity.segment
+      if segment.ready_to_send?
+        emitter.send_entity entity: segment
+      elsif streamer.eligible? segment: segment
+        streamer.stream_subsegments root: segment, emitter: emitter
+      end
+    end
+
+    # Record the passed block as a subsegment.
+    def capture(name, namespace: nil, segment: nil)
+      subsegment = begin_subsegment name, namespace: namespace, segment: segment
+      begin
+        yield subsegment
+      rescue Exception => e
+        subsegment.add_exception exception: e
+        raise e
+      ensure
+        end_subsegment
+      end
+    end
+
+    # Returns current segment or subsegment that associated to the current context.
+    # This is a proxy method to Context class current_entity.
+    def current_entity
+      context.current_entity
+    end
+
+    def inject_context(entity, target_ctx: nil)
+      context.inject_context entity, target_ctx: target_ctx
+      return unless block_given?
+      yield
+      context.clear!
+    end
+
+    def clear_context
+      context.clear!
+    end
+
+    def sampled?
+      entity = current_entity
+      if block_given?
+        yield if entity && entity.sampled
+      else
+        entity && entity.sampled
+      end
+    end
+
+    # A proxy method to get the annotations from the current active entity.
+    def annotations
+      entity = current_entity
+      if entity
+        entity.annotations
+      else
+        FacadeAnnotations
+      end
+    end
+
+    # A proxy method to get the metadata under provided namespace
+    # from the current active entity.
+    def metadata(namespace: :default)
+      entity = current_entity
+      if entity
+        entity.metadata(namespace: namespace)
+      else
+        FacadeMetadata
+      end
+    end
+
+    # A proxy method to XRay::Configuration.configure
+    def configure(user_config)
+      config.configure(user_config)
+    end
+
+    def context
+      config.context
+    end
+
+    def sampler
+      config.sampler
+    end
+
+    def emitter
+      config.emitter
+    end
+
+    def streamer
+      config.streamer
+    end
+
+    def segment_naming
+      config.segment_naming
+    end
+
+    def sampling_enabled?
+      config.sampling
+    end
+
+    private_class_method
+
+    def populate_runtime_context(segment)
+      aws = {}
+      config.plugins.each do |p|
+        meta = p.aws
+        if meta.is_a?(Hash) && !meta.empty?
+          aws.merge! meta
+          segment.origin = p::ORIGIN
+        end
+      end
+      segment.aws = aws unless aws.empty?
+    end
+  end
+end