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
Public Class Methods
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
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
# File lib/hubstep/tracer.rb, line 36 def enabled? !!@enabled end
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 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 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
# File lib/hubstep/tracer.rb, line 65 def should_emit?(verbose) @verbose || !verbose end
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
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
# 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
# File lib/hubstep/tracer.rb, line 173 def remove(span) if span == @spans.last # Common case @spans.pop else @spans.delete(span) end end