aws-xray-sdk 0.9.0

data/lib/aws-xray-sdk/facets/resources/aws_services_whitelist.rb

@@ -0,0 +1,147 @@
+module XRay
+  # AWS Services listed below will be recorded as subsegments
+  module AwsServices
+    # exausted list can be tracked at http://docs.aws.amazon.com/sdk-for-ruby/v3/api/Seahorse/Client/Base.html
+    @whitelist = %I[
+      ACM
+      APIGateway
+      AlexaForBusiness
+      AppStream
+      AppSync
+      ApplicationAutoScaling
+      ApplicationDiscoveryService
+      Athena
+      AutoScaling
+      Batch
+      Budgets
+      Cloud9
+      CloudDirectory
+      CloudFormatioin
+      CloudFront
+      CloudHSM
+      CloudHSMV2
+      CloudSearch
+      CloudSearchDomain
+      CloudTrail
+      CloudWatch
+      CloudWatchEvents
+      CloudWatchLogs
+      CodeBuild
+      CodeCommit
+      CodeDeploy
+      CodePipeline
+      CodeStar
+      CognitoIdentity
+      CognitoIdentityProvider
+      CognitoSync
+      Comprehend
+      ConfigService
+      CostExplore
+      CostandUsageReportService
+      DAX
+      DataPipeline
+      DatabaseMigrationService
+      DeviceFarm
+      DirectConnect
+      DirectoryService
+      DynamoDB
+      DynamoDBStreams
+      EC2
+      ECR
+      ECS
+      EFS
+      EMR
+      ElastiCache
+      ElasticBeanstalk
+      ElasticLoadBalancing
+      ElasticLoadBalancingV2
+      ElasticTranscoder
+      ElasticsearchService
+      Firehost
+      GameLift
+      Glacier
+      Glue
+      Greengrass
+      GuardDuty
+      Health
+      IAM
+      ImportExport
+      Inspector
+      IoT
+      IoTDataPlane
+      IoTJobsDataPlane
+      KMS
+      Kinesis
+      KinesisAnalytics
+      KinesisVideo
+      KinesisVideoArchiveMedia
+      KinesisVideoMedia
+      Lambda
+      LambdaPreview
+      Lex
+      LexModelBuildingService
+      LexRuntimeService
+      Lightsail
+      MQ
+      MTurk
+      MachineLearning
+      MarketplaceCommerceAnalytics
+      MarketplaceEntitlementService
+      MarketplaceMetering
+      MediaConvert
+      MediaLive
+      MediaPackage
+      MediaStore
+      MediaStoreData
+      MigrationHub
+      Mobile
+      OpsWorks
+      OpsWorksCM
+      Organizations
+      Pinpoint
+      Polly
+      Pricing
+      RDS
+      Redshift
+      Rekognition
+      ResourceGroups
+      ResourceGroupsTaggingAPI
+      Route53
+      Route53Domains
+      S3
+      SES
+      SFN
+      SMS
+      SNS
+      SQS
+      SSM
+      STS
+      SWF
+      SageMaker
+      SageMakerRuntime
+      ServerlessApplicationRepository
+      ServiceCatalog
+      ServiceDiscovery
+      Shield
+      SimpleDB
+      Snowball
+      States
+      StorageGateway
+      Support
+      Translate
+      WAF
+      WAFRegional
+      WorkDocs
+      WorkSpaces
+      XRay
+    ]
+
+    def self.whitelist
+      @whitelist
+    end
+
+    def self.whitelist=(v)
+      @whitelist = v
+    end
+  end
+end

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

@@ -0,0 +1,19 @@
+require 'logger'
+
+module XRay
+  # Provide global logger for classes that include this module.
+  # It serves as a proxy to global recorder's logger.
+  module Logging
+    def logger
+      Logging.logger
+    end
+
+    def self.logger
+      @logger ||= Logger.new($stdout).tap { |l| l.level = Logger::INFO }
+    end
+
+    def self.logger=(v)
+      @logger = v
+    end
+  end
+end

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

@@ -0,0 +1,97 @@
+require 'aws-xray-sdk/logger'
+require 'aws-xray-sdk/exceptions'
+
+module XRay
+  # Annotations are simple key-value pairs that are indexed for use with filter expressions.
+  # Use annotations to record data that you want to use to group traces in the console,
+  # or when calling the GetTraceSummaries API.
+  class Annotations
+    include Logging
+
+    def initialize(entity)
+      @entity = entity
+      @data = {}
+    end
+
+    def [](key)
+      @data[key]
+    end
+
+    # @param [Symbol] k Only characters in `A-Za-z0-9_` are supported.
+    # @param v Only `Numeric`, `String` true/false is supported.
+    def []=(k, v)
+      raise EntityClosedError if @entity.closed?
+      if key_supported?(k) && value_supported?(v)
+        @data[k] = v
+      else
+        logger.warn %(Dropping annotation with key #{k} due to invalid characters.)
+      end
+    end
+
+    # @param [Hash] h Update annotations with a single input hash.
+    def update(h)
+      raise EntityClosedError if @entity.closed?
+      filtered = filter_annotations(h)
+      @data.merge!(filtered)
+    end
+
+    def to_h
+      sanitize_values(@data)
+    end
+
+    private
+
+    def filter_annotations(h)
+      h.delete_if do |k, v|
+        drop = !key_supported?(k) || !value_supported?(v)
+        logger.warn %(Dropping annotation with key #{k} due to invalid characters.) if drop
+        drop
+      end
+    end
+
+    def sanitize_values(h)
+      h.each_pair do |k, v|
+        if v.is_a?(Float)
+          h[k] = v.to_s if v.nan? || v.infinite? == 1 || v.infinite? == -1
+        end
+      end
+    end
+
+    def key_supported?(k)
+      k.match(/[A-Za-z0-9_]+/)
+    end
+
+    def value_supported?(v)
+      case v
+      when Numeric
+        true
+      when true, false
+        true
+      else
+        v.is_a?(String)
+      end
+    end
+  end
+
+  # Singleton facade annotations class doing no-op for performance
+  # in case of not sampled X-Ray entities.
+  module FacadeAnnotations
+    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/cause.rb

@@ -0,0 +1,70 @@
+require 'oj'
+
+module XRay
+  # Represents cause section in segment and subsegment document.
+  # It records information about application runtime exceptions.
+  class Cause
+    attr_reader :id
+    @@depth = 15
+
+    def initialize(exception: nil, id: nil, remote: false)
+      if exception
+        @exception_h = normalize e: exception, remote: remote
+      end
+      @id = id
+    end
+
+    def to_h
+      return id if id
+      h = {
+        working_directory: Dir.pwd,
+        paths:             Gem.paths.path,
+        exceptions:        @exception_h
+      }
+      h
+    end
+
+    def to_json
+      @to_json ||= begin
+        Oj.dump to_h, mode: :compat, use_as_json: true
+      end
+    end
+
+    private
+
+    def normalize(e:, remote: false)
+      exceptions = []
+      exceptions << normalize_exception(e: e, remote: remote)
+
+      # don't propagate remote flag
+      while e.cause
+        exceptions << normalize_exception(e: e.cause)
+        e = e.cause
+      end
+
+      exceptions
+    end
+
+    def normalize_exception(e:, remote: false)
+      h = {
+        message: e.to_s,
+        type:    e.class.to_s
+      }
+      h[:remote] = true if remote
+
+      backtrace = e.backtrace_locations
+      return h unless backtrace
+      h[:stack] = backtrace.first(@@depth).collect do |t|
+        {
+          path:  t.path,
+          line:  t.lineno,
+          label: t.label
+        }
+      end
+
+      truncated = backtrace.size - @@depth
+      h[:truncated] = truncated if truncated > 0
+      h
+    end
+  end
+end

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

@@ -0,0 +1,72 @@
+require 'aws-xray-sdk/model/segment'
+require 'aws-xray-sdk/model/subsegment'
+require 'aws-xray-sdk/model/annotations'
+require 'aws-xray-sdk/model/metadata'
+
+module XRay
+  # defines common no-op methods for dummy segments/subsegments
+  module DummyEntity
+    def sampled
+      false
+    end
+
+    def annotations
+      FacadeAnnotations
+    end
+
+    def metadata(namespace: :default)
+      FacadeMetadata
+    end
+
+    def apply_status_code(status:)
+      # no-op
+    end
+
+    def merge_http_request(request:)
+      # no-op
+    end
+
+    def merge_http_response(response:)
+      # no-op
+    end
+
+    def add_exception(exception:, remote: false)
+      # no-op
+    end
+
+    def aws=(v)
+      # no-op
+    end
+
+    def to_h
+      # no-op
+    end
+
+    def to_json
+      # no-op
+    end
+  end
+
+  # A dummy segment is created when ``xray_recorder`` decides to not sample
+  # the segment based on sampling decisions.
+  # Adding data to a dummy segment becomes a no-op except for
+  # subsegments. This is to reduce the memory footprint of the SDK.
+  # A dummy segment will not be sent to the X-Ray daemon by the default emitter.
+  # Manually create dummy segments is not recommended.
+  class DummySegment < Segment
+    include DummyEntity
+  end
+
+  # A dummy subsegment will be created when ``xray_recorder`` tries
+  # to create a subsegment under a not sampled segment. Adding data
+  # to a dummy subsegment becomes no-op except for child subsegments.
+  # Dummy subsegment will not be sent to the X-Ray daemon by the default emitter.
+  # Manually create dummy subsegments is not recommended.
+  class DummySubsegment < Subsegment
+    include DummyEntity
+
+    def sql=(v)
+      # no-op
+    end
+  end
+end

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

@@ -0,0 +1,187 @@
+require 'securerandom'
+require 'bigdecimal'
+require 'oj'
+require 'aws-xray-sdk/exceptions'
+require 'aws-xray-sdk/model/cause'
+require 'aws-xray-sdk/model/annotations'
+require 'aws-xray-sdk/model/metadata'
+
+module XRay
+  # This module contains common properties and methods
+  # used by segment and subsegment class.
+  module Entity
+    attr_reader :name, :exception, :cause, :namespace,
+                :http_request, :http_response
+    attr_accessor :parent, :throttle, :error, :fault, :sampled, :aws,
+                  :start_time, :end_time
+
+    HTTP_REQUEST_KEY = %I[url method user_agent client_ip x_forwarded_for].freeze
+    HTTP_RESPONSE_KEY = %I[status content_length].freeze
+
+    # Generates a random 8-digit hex number as the entity id and returns it.
+    def id
+      @id ||= begin
+        SecureRandom.hex(8)
+      end
+    end
+
+    def closed?
+      @closed ||= false
+    end
+
+    # @param [Float] end_time End time on epoch.
+    def close(end_time: nil)
+      raise EntityClosedError if closed?
+      @end_time = end_time || Time.now.to_f
+      @closed = true
+    end
+
+    # @return [Array] The children subsegments of this entity.
+    def subsegments
+      @subsegments ||= []
+    end
+
+    # @param [Subsegment] subsegment Append the provided subsegment to children subsegments.
+    def add_subsegment(subsegment:)
+      raise EntityClosedError if closed?
+      subsegment.sampled = sampled
+      subsegment.parent = self
+      subsegments << subsegment
+      nil
+    end
+
+    # @param [Subsegment] subsegment Remove the provided subsegment from children subsegments.
+    # @return [Subsegment] The deleted subsegment if the deletion is successful.
+    def remove_subsegment(subsegment:)
+      subsegments.delete(subsegment)
+      subsegment
+    end
+
+    def annotations
+      @annotations ||= Annotations.new(self)
+    end
+
+    def metadata(namespace: :default)
+      @metadata ||= Metadata.new(self)
+      @metadata.sub_meta(namespace)
+    end
+
+    # Set error/fault/throttle flags based on http status code.
+    # This method is idempotent.
+    # @param [Integer] status
+    def apply_status_code(status:)
+      raise EntityClosedError if closed?
+      case status.to_i
+      when 429
+        @throttle = true
+        @error = true
+        @fault = false
+      when 400..499
+        @error = true
+        @throttle = false
+        @fault = false
+      when 500..599
+        @fault = true
+        @error = false
+        @throttle = false
+      end
+
+      @http_response ||= {}
+      @http_response[:status] = status.to_i
+    end
+
+    # @param [Hash] request Supported keys are `:url`, `:user_agent`, `:client_ip`,
+    #   `:x_forwarded_for`, `:method`. Value can be one of
+    #   String or Integer or Boolean types depend on the key.
+    def merge_http_request(request:)
+      raise EntityClosedError if closed?
+      request.delete_if { |k| !HTTP_REQUEST_KEY.include?(k) }
+      @http_request ||= {}
+      @http_request.merge!(request)
+    end
+
+    # @param [Hash] response Supported keys are `:status`, `:content_length`.
+    #   Value can be one of String or Integer types depend on the key.
+    def merge_http_response(response:)
+      raise EntityClosedError if closed?
+      response.delete_if { |k| !HTTP_RESPONSE_KEY.include?(k) }
+      @http_response ||= {}
+      @http_response.merge!(response)
+      apply_status_code status: response[:status] if response.key?(:status)
+    end
+
+    # @param [Exception] exception The exception object to capture.
+    # @param remote A boolean flag indicates whether the exception is
+    #   returned from the downstream service.
+    def add_exception(exception:, remote: false)
+      raise EntityClosedError if closed?
+      @fault = true
+      @exception = exception
+      if cause_id = find_root_cause(exception)
+        @cause = Cause.new id: cause_id
+      else
+        @cause = Cause.new exception: exception, remote: remote
+      end
+    end
+
+    # @return [String] Cause id is the id of the subsegment where
+    #   the exception originally comes from.
+    def cause_id
+      return @cause.id if @cause
+    end
+
+    # @return [Hash] The hash that contains all attributes that will
+    #   be later serialized and sent out.
+    def to_h
+      h = {
+        name:       name,
+        id:         id,
+        start_time: start_time
+      }
+      if closed?
+        h[:end_time] = end_time
+      else
+        h[:in_progress] = true
+      end
+      h[:subsegments] = subsegments unless subsegments.empty?
+      h[:aws] = aws if aws
+      if http_request || http_response
+        h[:http] = {}
+        h[:http][:request] = http_request if http_request
+        h[:http][:response] = http_response if http_response
+      end
+      if (a = annotations.to_h) && !a.empty?
+        h[:annotations] = a
+      end
+      if (m = @metadata) && !m.to_h.empty?
+        h[:metadata] = m.to_h
+      end
+
+      h[:parent_id] = parent.id if parent
+      # make sure the value in hash can only be boolean true
+      h[:fault] = !!fault if fault
+      h[:error] = !!error if error
+      h[:throttle] = !!throttle if throttle
+      h[:cause] = cause.to_h if cause
+      h
+    end
+
+    def to_json
+      @to_json ||= begin
+        Oj.dump to_h, mode: :compat, use_as_json: true
+      end
+    end
+
+    private
+
+    def find_root_cause(e)
+      subsegment = subsegments.find { |i| i.exception.hash == e.hash }
+      return nil unless subsegment
+      if cause_id = subsegment.cause_id
+        cause_id
+      else
+        subsegment.id
+      end
+    end
+  end
+end