Module: XRay::Entity

Included in:
Segment, Subsegment
Defined in:
lib/aws-xray-sdk/model/entity.rb

Overview

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

Constant Summary collapse

HTTP_REQUEST_KEY = 
%I[url method user_agent client_ip x_forwarded_for].freeze
HTTP_RESPONSE_KEY = 
%I[status content_length].freeze

Instance Attribute Summary collapse

Instance Method Summary collapse

Instance Attribute Details

#aws ⇒ Object

Returns the value of attribute aws.



15
16
17
 
# File 'lib/aws-xray-sdk/model/entity.rb', line 15

def aws
  @aws
end

#cause ⇒ Object (readonly)

Returns the value of attribute cause.



13
14
15
 
# File 'lib/aws-xray-sdk/model/entity.rb', line 13

def cause
  @cause
end

#end_time ⇒ Object

Returns the value of attribute end_time.



15
16
17
 
# File 'lib/aws-xray-sdk/model/entity.rb', line 15

def end_time
  @end_time
end

#error ⇒ Object

Returns the value of attribute error.



15
16
17
 
# File 'lib/aws-xray-sdk/model/entity.rb', line 15

def error
  @error
end

#exception ⇒ Object (readonly)

Returns the value of attribute exception.



13
14
15
 
# File 'lib/aws-xray-sdk/model/entity.rb', line 13

def exception
  @exception
end

#fault ⇒ Object

Returns the value of attribute fault.



15
16
17
 
# File 'lib/aws-xray-sdk/model/entity.rb', line 15

def fault
  @fault
end

#http_request ⇒ Object (readonly)

Returns the value of attribute http_request.



13
14
15
 
# File 'lib/aws-xray-sdk/model/entity.rb', line 13

def http_request
  @http_request
end

#http_response ⇒ Object (readonly)

Returns the value of attribute http_response.



13
14
15
 
# File 'lib/aws-xray-sdk/model/entity.rb', line 13

def http_response
  @http_response
end

#name ⇒ Object (readonly)

Returns the value of attribute name.



13
14
15
 
# File 'lib/aws-xray-sdk/model/entity.rb', line 13

def name
  @name
end

#namespace ⇒ Object (readonly)

Returns the value of attribute namespace.



13
14
15
 
# File 'lib/aws-xray-sdk/model/entity.rb', line 13

def namespace
  @namespace
end

#parent ⇒ Object

Returns the value of attribute parent.



15
16
17
 
# File 'lib/aws-xray-sdk/model/entity.rb', line 15

def parent
  @parent
end

#sampled ⇒ Object

Returns the value of attribute sampled.



15
16
17
 
# File 'lib/aws-xray-sdk/model/entity.rb', line 15

def sampled
  @sampled
end

#start_time ⇒ Object

Returns the value of attribute start_time.



15
16
17
 
# File 'lib/aws-xray-sdk/model/entity.rb', line 15

def start_time
  @start_time
end

#throttle ⇒ Object

Returns the value of attribute throttle.



15
16
17
 
# File 'lib/aws-xray-sdk/model/entity.rb', line 15

def throttle
  @throttle
end

Instance Method Details

#add_exception(exception:, remote: false) ⇒ Object

Parameters:

  • exception (Exception) —

    The exception object to capture.

  • remote (defaults to: false) —

    A boolean flag indicates whether the exception is returned from the downstream service.

Raises:



116
117
118
119
120
121
122
123
124
125
 
# 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:) ⇒ Object

Parameters:

  • subsegment (Subsegment) —

    Append the provided subsegment to children subsegments.

Raises:



45
46
47
48
49
50
51
 
# 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 ⇒ Object 



60
61
62
 
# File 'lib/aws-xray-sdk/model/entity.rb', line 60

def annotations
  @annotations ||= Annotations.new(self)
end

#apply_status_code(status:) ⇒ Object

Set error/fault/throttle flags based on http status code. This method is idempotent.

Parameters:

  • status (Integer)

Raises:



72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
 
# 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 ⇒ String

Returns Cause id is the id of the subsegment where the exception originally comes from.

Returns:

  • (String) —

    Cause id is the id of the subsegment where the exception originally comes from.



129
130
131
 
# File 'lib/aws-xray-sdk/model/entity.rb', line 129

def cause_id
  return @cause.id if @cause
end

#close(end_time: nil) ⇒ Object

Parameters:

  • end_time (Float) (defaults to: nil) —

    End time on epoch.

Raises:



33
34
35
36
37
 
# 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? ⇒ Boolean

Returns:

  • (Boolean) 


28
29
30
 
# File 'lib/aws-xray-sdk/model/entity.rb', line 28

def closed?
  @closed ||= false
end

#id ⇒ Object

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



22
23
24
25
26
 
# File 'lib/aws-xray-sdk/model/entity.rb', line 22

def id
  @id ||= begin
    SecureRandom.hex(8)
  end
end

#merge_http_request(request:) ⇒ Object

Parameters:

  • request (Hash) —

    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.

Raises:



96
97
98
99
100
101
 
# 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:) ⇒ Object

Parameters:

  • response (Hash) —

    Supported keys are ‘:status`, `:content_length`. Value can be one of String or Integer types depend on the key.

Raises:



105
106
107
108
109
110
111
 
# 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) ⇒ Object 



64
65
66
67
 
# 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:) ⇒ Subsegment

Returns The deleted subsegment if the deletion is successful.

Parameters:

  • subsegment (Subsegment) —

    Remove the provided subsegment from children subsegments.

Returns:

  • (Subsegment) —

    The deleted subsegment if the deletion is successful.



55
56
57
58
 
# File 'lib/aws-xray-sdk/model/entity.rb', line 55

def remove_subsegment(subsegment:)
  subsegments.delete(subsegment)
  subsegment
end

#subsegments ⇒ Array

Returns The children subsegments of this entity.

Returns:

  • (Array) —

    The children subsegments of this entity.



40
41
42
 
# File 'lib/aws-xray-sdk/model/entity.rb', line 40

def subsegments
  @subsegments ||= []
end

#to_h ⇒ Hash

Returns The hash that contains all attributes that will be later serialized and sent out.

Returns:

  • (Hash) —

    The hash that contains all attributes that will be later serialized and sent out.



135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
 
# 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
  # make sure @metadata is defined before evaluating it, to prevent warning `variable @metadata not initialized`
  if (defined?(@metadata) && 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 ⇒ Object 



172
173
174
175
176
 
# File 'lib/aws-xray-sdk/model/entity.rb', line 172

def to_json
  @to_json ||= begin
    MultiJson.dump(to_h)
  end
end