Class: HubStep::Tracer

Inherits:
Object
  • Object
show all
Defined in:
lib/hubstep/tracer.rb

Overview

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

Defined Under Namespace

Classes: InertSpan, InertSpanContext

Instance Attribute Summary collapse

Instance Method Summary collapse

Constructor Details

#initialize(transport: default_transport, tags: {}, verbose: true) ⇒ Tracer

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



19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
 
# 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

Instance Attribute Details

#enabled=(value) ⇒ Object (writeonly)

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.



44
45
46
 
# File 'lib/hubstep/tracer.rb', line 44

def enabled=(value)
  @enabled = value
end

Instance Method Details

#bottom_span ⇒ Object

Get the bottommost span in the stack

This is the span that has no children.

Returns a LightStep::Span or InertSpan.



60
61
62
63
 
# File 'lib/hubstep/tracer.rb', line 60

def bottom_span
  span = @spans.last if enabled?
  span || InertSpan.instance
end

#enabled? ⇒ Boolean

Returns:

  • (Boolean) 


36
37
38
 
# File 'lib/hubstep/tracer.rb', line 36

def enabled?
  !!@enabled
end

#flush ⇒ Object

Submit all buffered spans to the collector

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

Returns nothing.



125
126
127
 
# File 'lib/hubstep/tracer.rb', line 125

def flush
  @tracer.flush if enabled?
end

#inject(span_context, format, carrier) ⇒ Object

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.



149
150
151
152
153
 
# 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) ⇒ Object

Record an exception that happened during a span

span - Span or InertSpan instance exception - Exception instance

Returns nothing.



111
112
113
114
115
116
117
 
# 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) ⇒ Boolean

Returns:

  • (Boolean) 


65
66
67
 
# 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) ⇒ Object

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.



83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
 
# 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) ⇒ Object

Enable/disable the tracer within a block



47
48
49
50
51
52
53
 
# File 'lib/hubstep/tracer.rb', line 47

def with_enabled(value)
  original = enabled?
  self.enabled = value
  yield
ensure
  self.enabled = original
end