class LightStep::Span

Span represents an OpenTracer Span

See www.opentracing.io for more information.

Attributes

context[R]

Internal use only @private

dropped_logs[R]
end_micros[RW]

Internal use only @private

log_records[R]
operation_name[RW]

Part of the OpenTracing API

span_context[R]

Internal use only @private

start_micros[RW]

Internal use only @private

tags[R]

Internal use only @private

tracer[R]

Public Class Methods

new( tracer:, operation_name:, child_of: nil, references: [], start_micros:, tags: nil, max_log_records: ) click to toggle source

Creates a new {Span}

@param tracer [Tracer] the tracer that created this span @param operation_name [String] the operation name of this span. If it's

not a String it will be encoded with to_s.

@param child_of [SpanContext] the parent SpanContext (per child_of) @param references [Array<SpanContext>] 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.

@param start_micros [Numeric] start time of the span in microseconds @param tags [Hash] initial key:value tags (per set_tag) for the Span @param max_log_records [Numeric] maximum allowable number of log records

for the Span

@return [Span] a started Span

# 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

Public Instance Methods

dropped_logs_count() click to toggle source

Internal use only @private

# File lib/lightstep/span.rb, line 184
def dropped_logs_count
  dropped_logs.value
end
finish(end_time: Time.now) click to toggle source

Finish the {Span} @param end_time [Time] custom end time, if not now

# 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) click to toggle source

Get a baggage item @param key [String] the key of the baggage item @return Value of the baggage item

# File lib/lightstep/span.rb, line 112
def get_baggage_item(key)
  context.baggage[key]
end
log(event: nil, timestamp: Time.now, **fields) click to toggle source

@deprecated Use {#log_kv} instead. Add a log entry to this span @param event [String] event name for the log @param timestamp [Time] time of the log @param fields [Hash{Symbol=>Object}] Additional information to log

# 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) click to toggle source

Add a log entry to this span @param timestamp [Time] time of the log @param fields [Hash{Symbol=>Object}] Additional information to log

# 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() click to toggle source

Internal use only @private

# File lib/lightstep/span.rb, line 190
def logs_count
  log_records.size
end
set_baggage(baggage = {}) click to toggle source

Set all baggage at once. This will reset the baggage to the given param. @param baggage [Hash] new baggage for the span

# 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) click to toggle source

Set a baggage item on the span @param key [String] the key of the baggage item @param value [String] the value of the baggage item

# 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) click to toggle source

Set a tag value on this span @param key [String] the key of the tag @param value [String] the value of the tag. If it's not a String it will be encoded with to_s

# File lib/lightstep/span.rb, line 75
def set_tag(key, value)
  tags[key] = value.to_s
  self
end
to_h() click to toggle source

Hash representation of a span

# 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