Class: LightStep::Span

Inherits:
Object
  • Object
show all
Defined in:
lib/lightstep/span.rb

Overview

Span represents an OpenTracer Span

See www.opentracing.io for more information.

Instance Attribute Summary collapse

Instance Method Summary collapse

Constructor Details

#initialize(tracer:, operation_name:, child_of: nil, references: [], start_micros:, tags: nil, max_log_records:) ⇒ Span

Creates a new LightStep::Span

Parameters:

  • tracer (Tracer) —

    the tracer that created this span

  • operation_name (String) —

    the operation name of this span. If it’s not a String it will be encoded with to_s.

  • child_of (SpanContext) (defaults to: nil) —

    the parent SpanContext (per child_of)

  • references (Array<SpanContext>) (defaults to: []) —

    An array of SpanContexts that identify what Spans this Span follows from causally. Presently only one reference is supported, and cannot be provided in addition to a child_of.

  • start_micros (Numeric) —

    start time of the span in microseconds

  • tags (Hash) (defaults to: nil) —

    initial key:value tags (per set_tag) for the Span

  • max_log_records (Numeric) —

    maximum allowable number of log records for the Span



34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
 
# File 'lib/lightstep/span.rb', line 34

def initialize(
  tracer:,
  operation_name:,
  child_of: nil,
  references: [],
  start_micros:,
  tags: nil,
  max_log_records:
)

  @tags = Concurrent::Hash.new
  @tags.update(tags) unless tags.nil?
  @log_records = Concurrent::Array.new
  @dropped_logs = Concurrent::AtomicFixnum.new
  @max_log_records = max_log_records

  @tracer = tracer
  self.operation_name = operation_name.to_s
  self.start_micros = start_micros

  ref = child_of ? child_of : references
  ref = ref[0] if (Array === ref)
  ref = ref.context if (Span === ref)

  if SpanContext === ref
    @context = SpanContext.new(id: LightStep.guid, trace_id: ref.trace_id)
    set_baggage(ref.baggage)
    set_tag(:parent_span_guid, ref.id)
  else
    @context = SpanContext.new(id: LightStep.guid, trace_id: LightStep.guid)
  end
end

Instance Attribute Details

#context ⇒ Object (readonly) Also known as: span_context

Internal use only



14
15
16
 
# File 'lib/lightstep/span.rb', line 14

def context
  @context
end

#end_micros ⇒ Object

Internal use only



14
15
16
 
# File 'lib/lightstep/span.rb', line 14

def end_micros
  @end_micros
end

#operation_name ⇒ Object

Internal use only



14
15
16
 
# File 'lib/lightstep/span.rb', line 14

def operation_name
  @operation_name
end

#start_micros ⇒ Object

Internal use only



14
15
16
 
# File 'lib/lightstep/span.rb', line 14

def start_micros
  @start_micros
end

#tags ⇒ Object (readonly)

Internal use only



14
15
16
 
# File 'lib/lightstep/span.rb', line 14

def tags
  @tags
end

Instance Method Details

#dropped_logs_count ⇒ Object

Internal use only



163
164
165
 
# File 'lib/lightstep/span.rb', line 163

def dropped_logs_count
  dropped_logs.value
end

#finish(end_time: Time.now) ⇒ Object

Finish the LightStep::Span

Parameters:

  • end_time (Time) (defaults to: Time.now) —

    custom end time, if not now



135
136
137
138
139
140
141
 
# File 'lib/lightstep/span.rb', line 135

def finish(end_time: Time.now)
  if end_micros.nil?
    self.end_micros = LightStep.micros(end_time)
  end
  tracer.finish_span(self)
  self
end

#get_baggage_item(key) ⇒ Object

Get a baggage item

Parameters:

  • key (String) —

    the key of the baggage item

Returns:

  • Value of the baggage item



104
105
106
 
# File 'lib/lightstep/span.rb', line 104

def get_baggage_item(key)
  context.baggage[key]
end

#log(event: nil, timestamp: Time.now, **fields) ⇒ Object

Add a log entry to this span

Parameters:

  • event (String) (defaults to: nil) —

    event name for the log

  • timestamp (Time) (defaults to: Time.now) —

    time of the log

  • fields (Hash) —

    Additional information to log



112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
 
# File 'lib/lightstep/span.rb', line 112

def log(event: nil, timestamp: Time.now, **fields)
  return unless tracer.enabled?

  fields = {} if fields.nil?
  unless event.nil?
	fields[:event] = event.to_s
  end
  record = {
    timestamp_micros: LightStep.micros(timestamp),
    fields: fields.to_a.map {|key, value|
      {Key: key.to_s, Value: value.to_s}
    },
  }

  log_records.push(record)
  if log_records.size > @max_log_records
    log_records.shift
    dropped_logs.increment
  end
end

#logs_count ⇒ Object

Internal use only



169
170
171
 
# File 'lib/lightstep/span.rb', line 169

def logs_count
  log_records.size
end

#set_baggage(baggage = {}) ⇒ Object

Set all baggage at once. This will reset the baggage to the given param.

Parameters:

  • baggage (Hash) (defaults to: {}) —

    new baggage for the span



93
94
95
96
97
98
99
 
# File 'lib/lightstep/span.rb', line 93

def set_baggage(baggage = {})
  @context = SpanContext.new(
    id: context.id,
    trace_id: context.trace_id,
    baggage: baggage
  )
end

#set_baggage_item(key, value) ⇒ Object

Set a baggage item on the span

Parameters:

  • key (String) —

    the key of the baggage item

  • value (String) —

    the value of the baggage item



82
83
84
85
86
87
88
89
 
# File 'lib/lightstep/span.rb', line 82

def set_baggage_item(key, value)
  @context = SpanContext.new(
    id: context.id,
    trace_id: context.trace_id,
    baggage: context.baggage.merge({key => value})
  )
  self
end

#set_tag(key, value) ⇒ Object

Set a tag value on this span it will be encoded with to_s

Parameters:

  • key (String) —

    the key of the tag

  • value (String) —

    the value of the tag. If it’s not a String



71
72
73
74
 
# File 'lib/lightstep/span.rb', line 71

def set_tag(key, value)
  tags[key] = value.to_s
  self
end

#to_h ⇒ Object

Hash representation of a span



144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
 
# File 'lib/lightstep/span.rb', line 144

def to_h
  {
    runtime_guid: tracer.guid,
    span_guid: context.id,
    trace_guid: context.trace_id,
    span_name: operation_name,
    attributes: tags.map {|key, value|
      {Key: key.to_s, Value: value}
    },
    oldest_micros: start_micros,
    youngest_micros: end_micros,
    error_flag: false,
    dropped_logs: dropped_logs_count,
    log_records: log_records
  }
end