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
66
67
68
69
 
# 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.each { |k, v| tags[k] = v.to_s }) 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,
      trace_id_upper64: ref.trace_id_upper64,
      sampled: ref.sampled?)
    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



184
185
186
 
# File 'lib/lightstep/span.rb', line 184

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



156
157
158
159
160
161
162
 
# File 'lib/lightstep/span.rb', line 156

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



112
113
114
 
# File 'lib/lightstep/span.rb', line 112

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

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

Deprecated.

Use #log_kv instead.

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{Symbol=>Object}) —

    Additional information to log



121
122
123
124
125
126
127
128
129
130
131
 
# File 'lib/lightstep/span.rb', line 121

def log(event: nil, timestamp: Time.now, **fields)
  warn 'Span#log is deprecated. Please use Span#log_kv instead.'
  return unless tracer.enabled?

  fields = {} if fields.nil?
  unless event.nil?
	fields[:event] = event.to_s
  end

  log_kv(timestamp: timestamp, **fields)
end

#log_kv(timestamp: Time.now, **fields) ⇒ Object

Add a log entry to this span

Parameters:

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

    time of the log

  • fields (Hash{Symbol=>Object}) —

    Additional information to log



136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
 
# File 'lib/lightstep/span.rb', line 136

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

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

  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



190
191
192
 
# File 'lib/lightstep/span.rb', line 190

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



99
100
101
102
103
104
105
106
107
 
# File 'lib/lightstep/span.rb', line 99

def set_baggage(baggage = {})
  @context = SpanContext.new(
    id: context.id,
    trace_id: context.trace_id,
    trace_id_upper64: context.trace_id_upper64,
    sampled: context.sampled?,
    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



86
87
88
89
90
91
92
93
94
95
 
# File 'lib/lightstep/span.rb', line 86

def set_baggage_item(key, value)
  @context = SpanContext.new(
    id: context.id,
    trace_id: context.trace_id,
    trace_id_upper64: context.trace_id_upper64,
    sampled: context.sampled?,
    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



75
76
77
78
 
# File 'lib/lightstep/span.rb', line 75

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

#to_h ⇒ Object

Hash representation of a span



165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
 
# File 'lib/lightstep/span.rb', line 165

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