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.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, 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



178
179
180
 
# File 'lib/lightstep/span.rb', line 178

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



150
151
152
153
154
155
156
 
# File 'lib/lightstep/span.rb', line 150

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



106
107
108
 
# File 'lib/lightstep/span.rb', line 106

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



115
116
117
118
119
120
121
122
123
124
125
 
# File 'lib/lightstep/span.rb', line 115

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



130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
 
# File 'lib/lightstep/span.rb', line 130

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



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

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



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

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



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

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



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



159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
 
# File 'lib/lightstep/span.rb', line 159

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