module XRay::Entity

This module contains common properties and methods used by segment and subsegment class.

Constants

HTTP_REQUEST_KEY
HTTP_RESPONSE_KEY

Attributes

aws[RW]
cause[R]
end_time[RW]
error[RW]
exception[R]
fault[RW]
http_request[R]
http_response[R]
name[R]
namespace[R]
parent[RW]
sampled[RW]
start_time[RW]
throttle[RW]

Public Instance Methods

add_exception(exception:, remote: false) click to toggle source

@param [Exception] exception The exception object to capture. @param remote A boolean flag indicates whether the exception is

returned from the downstream service.
# File lib/aws-xray-sdk/model/entity.rb, line 116
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
add_subsegment(subsegment:) click to toggle source

@param [Subsegment] subsegment Append the provided subsegment to children subsegments.

# File lib/aws-xray-sdk/model/entity.rb, line 45
def add_subsegment(subsegment:)
  raise EntityClosedError if closed?
  subsegment.sampled = sampled
  subsegment.parent = self
  subsegments << subsegment
  nil
end
annotations() click to toggle source
# File lib/aws-xray-sdk/model/entity.rb, line 60
def annotations
  @annotations ||= Annotations.new(self)
end
apply_status_code(status:) click to toggle source

Set error/fault/throttle flags based on http status code. This method is idempotent. @param [Integer] status

# File lib/aws-xray-sdk/model/entity.rb, line 72
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
cause_id() click to toggle source

@return [String] Cause id is the id of the subsegment where

the exception originally comes from.
# File lib/aws-xray-sdk/model/entity.rb, line 129
def cause_id
  return @cause.id if @cause
end
close(end_time: nil) click to toggle source

@param [Float] end_time End time on epoch.

# File lib/aws-xray-sdk/model/entity.rb, line 33
def close(end_time: nil)
  raise EntityClosedError if closed?
  @end_time = end_time || Time.now.to_f
  @closed = true
end
closed?() click to toggle source
# File lib/aws-xray-sdk/model/entity.rb, line 28
def closed?
  @closed ||= false
end
id() click to toggle source

Generates a random 8-digit hex number as the entity id and returns it.

# File lib/aws-xray-sdk/model/entity.rb, line 22
def id
  @id ||= begin
    SecureRandom.hex(8)
  end
end
merge_http_request(request:) click to toggle source

@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.
# File lib/aws-xray-sdk/model/entity.rb, line 96
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
merge_http_response(response:) click to toggle source

@param [Hash] response Supported keys are `:status`, `:content_length`.

Value can be one of String or Integer types depend on the key.
# File lib/aws-xray-sdk/model/entity.rb, line 105
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
metadata(namespace: :default) click to toggle source
# File lib/aws-xray-sdk/model/entity.rb, line 64
def metadata(namespace: :default)
  @metadata ||= Metadata.new(self)
  @metadata.sub_meta(namespace)
end
remove_subsegment(subsegment:) click to toggle source

@param [Subsegment] subsegment Remove the provided subsegment from children subsegments. @return [Subsegment] The deleted subsegment if the deletion is successful.

# File lib/aws-xray-sdk/model/entity.rb, line 55
def remove_subsegment(subsegment:)
  subsegments.delete(subsegment)
  subsegment
end
subsegments() click to toggle source

@return [Array] The children subsegments of this entity.

# File lib/aws-xray-sdk/model/entity.rb, line 40
def subsegments
  @subsegments ||= []
end
to_h() click to toggle source

@return [Hash] The hash that contains all attributes that will

be later serialized and sent out.
# File lib/aws-xray-sdk/model/entity.rb, line 135
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.map(&:to_h) 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
to_json() click to toggle source
# File lib/aws-xray-sdk/model/entity.rb, line 171
def to_json
  @to_json ||= begin
    MultiJson.dump(to_h)
  end
end

Private Instance Methods

find_root_cause(e) click to toggle source
# File lib/aws-xray-sdk/model/entity.rb, line 179
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