class HubStep::Tracer

Tracer wraps LightStep::Tracer. It provides a block-based API for creating and configuring spans and support for enabling and disabling tracing at runtime.

Attributes

enabled[W]

Enable/disable the tracer at runtime

When disabled, all span blocks will be passed InertSpans instead of real spans. Operations on InertSpan are no-ops.

Public Class Methods

new(transport: default_transport, tags: {}, verbose: true) click to toggle source

Create a Tracer.

tags - Hash of tags to assign to the tracer. These will be

associated with every span the tracer creates.

transport - instance of a LightStep::Transport::Base subclass verbose - Whether or not to emit verbose spans, default true

# File lib/hubstep/tracer.rb, line 19
def initialize(transport: default_transport, tags: {}, verbose: true)
  @verbose = verbose

  name = HubStep.server_metadata.values_at("app", "role").join("-")

  default_tags = {
    "hostname" => HubStep.hostname,
  }

  @tracer = LightStep::Tracer.new(component_name: name,
                                  transport: transport,
                                  tags: default_tags.merge(tags))

  @spans = []
  self.enabled = false
end

Public Instance Methods

bottom_span() click to toggle source

Get the bottommost span in the stack

This is the span that has no children.

Returns a LightStep::Span or InertSpan.

# File lib/hubstep/tracer.rb, line 60
def bottom_span
  span = @spans.last if enabled?
  span || InertSpan.instance
end
enabled?() click to toggle source
# File lib/hubstep/tracer.rb, line 36
def enabled?
  !!@enabled
end
flush() click to toggle source

Submit all buffered spans to the collector

This happens automatically so you probably don't need to call this outside of tests.

Returns nothing.

# File lib/hubstep/tracer.rb, line 125
def flush
  @tracer.flush if enabled?
end
inject(span_context, format, carrier) click to toggle source

Inject a SpanContext into the given carrier

span_context - A SpanContext format - A LightStep::Tracer format carrier - A Hash

Example:

tracer.span("request") do |span|
  carrier = {}
  tracer.inject(
    span.span_context,
    LightStep::Tracer::FORMAT_TEXT_MAP,
    carrier
  )

  client.request(data, headers: carrier)
end

Returns nil but mutates the carrier.

# File lib/hubstep/tracer.rb, line 149
def inject(span_context, format, carrier)
  return unless enabled?

  @tracer.inject(span_context, format, carrier)
end
record_exception(span, exception) click to toggle source

Record an exception that happened during a span

span - Span or InertSpan instance exception - Exception instance

Returns nothing.

# File lib/hubstep/tracer.rb, line 111
def record_exception(span, exception)
  span.configure do
    span.set_tag("error", true)
    span.set_tag("error.class", exception.class.name)
    span.set_tag("error.message", exception.message)
  end
end
should_emit?(verbose) click to toggle source
# File lib/hubstep/tracer.rb, line 65
def should_emit?(verbose)
  @verbose || !verbose
end
span(operation_name, start_time: nil, tags: nil, finish: true, verbose: false) { |instance| ... } click to toggle source

Record a span representing the execution of the given block

operation_name - short human-readable String identifying the work done by the span start_time - Time instance representing when the span began tags - Hash of String => String tags to add to the span finish - Boolean indicating whether to “finish” (i.e., record the

span's end time and submit it to the collector).
Defaults to true.

verbose - Boolean indicating this is a ancilary span, only

emitted when the tracer has verbose enabled, default
false

Yields a LightStep::Span or InertSpan to the block. Returns the block's return value.

# File lib/hubstep/tracer.rb, line 83
def span(operation_name, start_time: nil, tags: nil, finish: true, verbose: false)
  unless enabled? && should_emit?(verbose)
    return yield InertSpan.instance
  end

  span = @tracer.start_span(operation_name,
                            child_of: @spans.last,
                            start_time: start_time,
                            tags: tags)
  @spans << span

  begin
    yield span
  ensure
    record_exception(span, $ERROR_INFO) if $ERROR_INFO

    remove(span)

    span.finish if finish && span.end_micros.nil?
  end
end
with_enabled(value) { || ... } click to toggle source

Enable/disable the tracer within a block

# File lib/hubstep/tracer.rb, line 47
def with_enabled(value)
  original = enabled?
  self.enabled = value
  yield
ensure
  self.enabled = original
end

Private Instance Methods

default_transport() click to toggle source
# File lib/hubstep/tracer.rb, line 157
def default_transport
  host = ENV["LIGHTSTEP_COLLECTOR_HOST"]
  port = ENV["LIGHTSTEP_COLLECTOR_PORT"]
  encryption = ENV["LIGHTSTEP_COLLECTOR_ENCRYPTION"]
  access_token = ENV["LIGHTSTEP_ACCESS_TOKEN"]

  if host && port && encryption && access_token
    HubStep::Transport::HTTPJSON.new(host: host,
                                     port: port.to_i,
                                     encryption: encryption,
                                     access_token: access_token)
  else
    LightStep::Transport::Nil.new
  end
end
remove(span) click to toggle source
# File lib/hubstep/tracer.rb, line 173
def remove(span)
  if span == @spans.last
    # Common case
    @spans.pop
  else
    @spans.delete(span)
  end
end