Class: XRay::Recorder

Inherits:
Object
  • Object
show all
Defined in:
lib/aws-xray-sdk/recorder.rb

Overview

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.

Instance Attribute Summary collapse

Instance Method Summary collapse

Constructor Details

#initialize(user_config: nil) ⇒ Recorder

Returns a new instance of Recorder.



16
17
18
19
 
# File 'lib/aws-xray-sdk/recorder.rb', line 16

def initialize(user_config: nil)
  @config = Configuration.new
  @config.configure(user_config) unless user_config.nil?
end

Instance Attribute Details

#config ⇒ Object (readonly)

Returns the value of attribute config.



14
15
16
 
# File 'lib/aws-xray-sdk/recorder.rb', line 14

def config
  @config
end

Instance Method Details

#annotations ⇒ Object

A proxy method to get the annotations from the current active entity.



146
147
148
149
150
151
152
153
 
# File 'lib/aws-xray-sdk/recorder.rb', line 146

def annotations
  entity = current_entity
  if entity
    entity.annotations
  else
    FacadeAnnotations
  end
end

#begin_segment(name, trace_id: nil, parent_id: nil, sampled: nil) ⇒ Segment

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.

Returns:

  • (Segment) —

    thew newly created segment.

Raises:



25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
 
# File 'lib/aws-xray-sdk/recorder.rb', line 25

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

#begin_subsegment(name, namespace: nil, segment: nil) ⇒ Subsegment

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.

Returns:



61
62
63
64
65
66
67
68
69
70
71
72
73
74
 
# File 'lib/aws-xray-sdk/recorder.rb', line 61

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

#capture(name, namespace: nil, segment: nil) ⇒ Object

Record the passed block as a subsegment.



107
108
109
110
111
112
113
114
115
116
117
 
# File 'lib/aws-xray-sdk/recorder.rb', line 107

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

#clear_context ⇒ Object 



132
133
134
 
# File 'lib/aws-xray-sdk/recorder.rb', line 132

def clear_context
  context.clear!
end

#configure(user_config) ⇒ Object

A proxy method to XRay::Configuration.configure



167
168
169
 
# File 'lib/aws-xray-sdk/recorder.rb', line 167

def configure(user_config)
  config.configure(user_config)
end

#context ⇒ Object 



171
172
173
 
# File 'lib/aws-xray-sdk/recorder.rb', line 171

def context
  config.context
end

#current_entity ⇒ Object

Returns current segment or subsegment that associated to the current context. This is a proxy method to Context class current_entity.



121
122
123
 
# File 'lib/aws-xray-sdk/recorder.rb', line 121

def current_entity
  context.current_entity
end

#current_segment ⇒ Segment

Returns the active segment tied to the current context. If the current context is under a subsegment, it returns its parent segment.

Returns:

  • (Segment) —

    the active segment tied to the current context. If the current context is under a subsegment, it returns its parent segment.



43
44
45
46
 
# File 'lib/aws-xray-sdk/recorder.rb', line 43

def current_segment
  entity = current_entity
  entity.segment if entity
end

#current_subsegment ⇒ Subsegment

The active subsegment tied to the current context. Returns nil if the current context has no associated subsegment.

Returns:

  • (Subsegment) —

    the active subsegment tied to the current context. Returns nil if the current context has no associated subsegment.



78
79
80
81
 
# File 'lib/aws-xray-sdk/recorder.rb', line 78

def current_subsegment
  entity = context.current_entity
  entity.is_a?(Subsegment) ? entity : nil
end

#emitter ⇒ Object 



179
180
181
 
# File 'lib/aws-xray-sdk/recorder.rb', line 179

def emitter
  config.emitter
end

#end_segment(end_time: nil) ⇒ Object

End the current segment and send it to X-Ray daemon if it is ready.



49
50
51
52
53
54
55
 
# File 'lib/aws-xray-sdk/recorder.rb', line 49

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

#end_subsegment(end_time: nil) ⇒ Object

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.



86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
 
# File 'lib/aws-xray-sdk/recorder.rb', line 86

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

#inject_context(entity, target_ctx: nil) ⇒ Object 



125
126
127
128
129
130
 
# File 'lib/aws-xray-sdk/recorder.rb', line 125

def inject_context(entity, target_ctx: nil)
  context.inject_context entity, target_ctx: target_ctx
  return unless block_given?
  yield
  context.clear!
end

#metadata(namespace: :default) ⇒ Object

A proxy method to get the metadata under provided namespace from the current active entity.



157
158
159
160
161
162
163
164
 
# File 'lib/aws-xray-sdk/recorder.rb', line 157

def metadata(namespace: :default)
  entity = current_entity
  if entity
    entity.metadata(namespace: namespace)
  else
    FacadeMetadata
  end
end

#populate_runtime_context(segment) ⇒ Object 



197
198
199
200
201
202
203
204
205
206
207
 
# File 'lib/aws-xray-sdk/recorder.rb', line 197

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

#sampled? ⇒ Boolean

Returns:

  • (Boolean) 


136
137
138
139
140
141
142
143
 
# File 'lib/aws-xray-sdk/recorder.rb', line 136

def sampled?
  entity = current_entity
  if block_given?
    yield if entity && entity.sampled
  else
    entity && entity.sampled
  end
end

#sampler ⇒ Object 



175
176
177
 
# File 'lib/aws-xray-sdk/recorder.rb', line 175

def sampler
  config.sampler
end

#sampling_enabled? ⇒ Boolean

Returns:

  • (Boolean) 


191
192
193
 
# File 'lib/aws-xray-sdk/recorder.rb', line 191

def sampling_enabled?
  config.sampling
end

#segment_naming ⇒ Object 



187
188
189
 
# File 'lib/aws-xray-sdk/recorder.rb', line 187

def segment_naming
  config.segment_naming
end

#streamer ⇒ Object 



183
184
185
 
# File 'lib/aws-xray-sdk/recorder.rb', line 183

def streamer
  config.streamer
end