Class: LightStep::Tracer

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

Direct Known Subclasses

GlobalTracer

Defined Under Namespace

Classes: ConfigurationError, Error

Constant Summary collapse

DEFAULT_MAX_LOG_RECORDS = 
1000
MIN_MAX_LOG_RECORDS = 
1
DEFAULT_MAX_SPAN_RECORDS = 
1000
MIN_MAX_SPAN_RECORDS = 
1

Instance Attribute Summary collapse

Instance Method Summary collapse

Constructor Details

#initialize(component_name:, access_token: nil, transport: nil, tags: {}, propagator: :lightstep) ⇒ Object

Initialize a new tracer. Either an access_token or a transport must be provided. A component_name is always required.

Parameters:

  • component_name (String) —

    Component name to use for the tracer

  • access_token (String) (defaults to: nil) —

    The project access token when pushing to LightStep

  • transport (LightStep::Transport::Base) (defaults to: nil) —

    How the data should be transported

  • tags (Hash) (defaults to: {}) —

    Tracer-level tags

  • propagator (Propagator) (defaults to: :lightstep) —

    Symbol one of :lightstep, :b3 indicating the propagator to use

Raises:

  • LightStep::ConfigurationError if the group name or access token is not a valid string.



35
36
37
38
39
40
41
42
43
44
45
 
# File 'lib/lightstep/tracer.rb', line 35

def initialize(component_name:,
               access_token: nil,
               transport: nil,
               tags: {},
               propagator: :lightstep)
  configure(component_name: component_name,
            access_token: access_token,
            transport: transport,
            tags: tags,
            propagator: propagator)
end

Instance Attribute Details

#access_token ⇒ Object (readonly)

Returns the value of attribute access_token.



23
24
25
 
# File 'lib/lightstep/tracer.rb', line 23

def access_token
  @access_token
end

#guid ⇒ Object (readonly)

Returns the value of attribute guid.



23
24
25
 
# File 'lib/lightstep/tracer.rb', line 23

def guid
  @guid
end

Instance Method Details

#active_span ⇒ Span?

Returns the span from the active scope, if any.

Returns:

  • (Span, nil) —

    the active span. This is a shorthand for ‘scope_manager.active.span`, and nil will be returned if Scope#active is nil.



144
145
146
147
 
# File 'lib/lightstep/tracer.rb', line 144

def active_span
  scope = scope_manager.active
  scope.span if scope
end

#disable(discard: true) ⇒ Object

Disables the tracer

Parameters:

  • discard (Boolean) (defaults to: true) —

    whether to discard queued data



226
227
228
229
230
 
# File 'lib/lightstep/tracer.rb', line 226

def disable(discard: true)
  @enabled = false
  @reporter.clear if discard
  @reporter.flush
end

#enable ⇒ Object

Enables the tracer



220
221
222
 
# File 'lib/lightstep/tracer.rb', line 220

def enable
  @enabled = true
end

#enabled? ⇒ Boolean

Returns true if the tracer is enabled.

Returns:

  • (Boolean) —

    true if the tracer is enabled



214
215
216
217
 
# File 'lib/lightstep/tracer.rb', line 214

def enabled?
  return @enabled if defined?(@enabled)
  @enabled = true
end

#extract(format, carrier) ⇒ SpanContext

Extract a SpanContext from a carrier

Parameters:

  • format (OpenTracing::FORMAT_TEXT_MAP, OpenTracing::FORMAT_BINARY, OpenTracing::FORMAT_RACK)
  • carrier (Carrier) —

    A carrier object of the type dictated by the specified ‘format`

Returns:

  • (SpanContext) —

    the extracted SpanContext or nil if none could be found



209
210
211
 
# File 'lib/lightstep/tracer.rb', line 209

def extract(format, carrier)
  @propagator.extract(format, carrier)
end

#finish_span(span) ⇒ Object

Internal use only.



240
241
242
243
 
# File 'lib/lightstep/tracer.rb', line 240

def finish_span(span)
  return unless enabled?
  @reporter.add_span(span)
end

#flush ⇒ Object

Flush to the Transport



233
234
235
236
 
# File 'lib/lightstep/tracer.rb', line 233

def flush
  return unless enabled?
  @reporter.flush
end

#inject(span_context, format, carrier) ⇒ Object

Inject a SpanContext into the given carrier

Parameters:

  • spancontext (SpanContext)
  • format (OpenTracing::FORMAT_TEXT_MAP, OpenTracing::FORMAT_BINARY)
  • carrier (Carrier) —

    A carrier object of the type dictated by the specified ‘format`



201
202
203
 
# File 'lib/lightstep/tracer.rb', line 201

def inject(span_context, format, carrier)
  @propagator.inject(span_context, format, carrier)
end

#max_log_records ⇒ Object 



47
48
49
 
# File 'lib/lightstep/tracer.rb', line 47

def max_log_records
  @max_log_records ||= DEFAULT_MAX_LOG_RECORDS
end

#max_log_records=(max) ⇒ Object 



51
52
53
 
# File 'lib/lightstep/tracer.rb', line 51

def max_log_records=(max)
  @max_log_records = [MIN_MAX_LOG_RECORDS, max].max
end

#max_span_records ⇒ Object 



55
56
57
 
# File 'lib/lightstep/tracer.rb', line 55

def max_span_records
  @max_span_records ||= DEFAULT_MAX_SPAN_RECORDS
end

#max_span_records=(max) ⇒ Object 



59
60
61
62
 
# File 'lib/lightstep/tracer.rb', line 59

def max_span_records=(max)
  @max_span_records = [MIN_MAX_SPAN_RECORDS, max].max
  @reporter.max_span_records = @max_span_records
end

#report_period_seconds=(seconds) ⇒ Object

Set the report flushing period. If set to 0, no flushing will be done, you must manually call flush.



66
67
68
 
# File 'lib/lightstep/tracer.rb', line 66

def report_period_seconds=(seconds)
  @reporter.period = seconds
end

#scope_manager ⇒ ScopeManager

Creates a scope manager or returns the already-created one.

Returns:

  • (ScopeManager) —

    the current ScopeManager, which may be a no-op but may not be nil.



76
77
78
 
# File 'lib/lightstep/tracer.rb', line 76

def scope_manager
  @scope_manager ||= LightStep::ScopeManager.new
end

#start_active_span(operation_name, child_of: nil, references: nil, start_time: Time.now, tags: nil, ignore_active_scope: false, finish_on_close: true) {|Scope| ... } ⇒ Scope, Object

Returns a newly started and activated Scope.

If ScopeManager#active is not nil, no explicit references are provided, and ‘ignore_active_scope` is false, then an inferred References#CHILD_OF reference is created to the ScopeManager#active’s SpanContext when start_active_span is invoked.

If specified, the `references` parameter must be omitted.

Parameters:

  • operation_name (String) —

    The operation name for the Span

  • child_of (SpanContext, Span) (defaults to: nil) —

    SpanContext that acts as a parent to the newly-started Span. If a Span instance is provided, its context is automatically substituted. See [Reference] for more information.

  • references (Array<Reference>) (defaults to: nil) —

    An array of reference objects that identify one or more parent SpanContexts.

  • start_time (Time) (defaults to: Time.now) —

    When the Span started, if not now

  • tags (Hash) (defaults to: nil) —

    Tags to assign to the Span at start time

  • ignore_active_scope (Boolean) (defaults to: false) —

    whether to create an implicit References#CHILD_OF reference to the ScopeManager#active.

  • finish_on_close (Boolean) (defaults to: true) —

    whether span should automatically be finished when Scope#close is called

Yields:

  • (Scope) —

    If an optional block is passed to start_active_span it will yield the newly-started Scope. If ‘finish_on_close` is true then the Span will be finished automatically after the block is executed.

Returns:

  • (Scope, Object) —

    If passed an optional block, start_active_span returns the block’s return value, otherwise it returns the newly-started and activated Scope



108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
 
# File 'lib/lightstep/tracer.rb', line 108

def start_active_span(operation_name,
                      child_of: nil,
                      references: nil,
                      start_time: Time.now,
                      tags: nil,
                      ignore_active_scope: false,
                      finish_on_close: true)
  if child_of.nil? && references.nil? && !ignore_active_scope
    child_of = active_span
  end

  span = start_span(
    operation_name,
    child_of: child_of,
    references: references,
    start_time: start_time,
    tags: tags,
    ignore_active_scope: ignore_active_scope
  )

  scope_manager.activate(span: span, finish_on_close: finish_on_close).tap do |scope|
    if block_given?
      begin
        return yield scope
      ensure
        scope.close
      end
    end
  end
end

#start_span(operation_name, child_of: nil, references: nil, start_time: nil, tags: nil, ignore_active_scope: false) {|Span| ... } ⇒ Span, Object

Starts a new span.

Parameters:

  • operation_name (String) —

    The operation name for the Span

  • child_of (SpanContext) (defaults to: nil) —

    SpanContext that acts as a parent to the newly-started Span. If a Span instance is provided, its .span_context is automatically substituted.

  • references (Array<SpanContext>) (defaults to: nil) —

    An array of SpanContexts that identify any parent SpanContexts of newly-started Span. If Spans are provided, their .span_context is automatically substituted.

  • start_time (Time) (defaults to: nil) —

    When the Span started, if not now

  • tags (Hash) (defaults to: nil) —

    Tags to assign to the Span at start time

  • ignore_active_scope (Boolean) (defaults to: false) —

    whether to create an implicit References#CHILD_OF reference to the ScopeManager#active.

Yields:

  • (Span) —

    If passed an optional block, start_span will yield the newly-created span to the block. The span will be finished automatically after the block is executed.

Returns:

  • (Span, Object) —

    If passed an optional block, start_span will return the block’s return value, otherwise it returns the newly-started Span instance, which has not been automatically registered via the ScopeManager



169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
 
# File 'lib/lightstep/tracer.rb', line 169

def start_span(operation_name, child_of: nil, references: nil, start_time: nil, tags: nil, ignore_active_scope: false)
  if child_of.nil? && references.nil? && !ignore_active_scope
    child_of = active_span
  end

  span_options = {
    tracer: self,
    operation_name: operation_name,
    child_of: child_of,
    references: references,
    start_micros: start_time.nil? ? LightStep.micros(Time.now) : LightStep.micros(start_time),
    tags: tags,
    max_log_records: max_log_records,
  }

  Span.new(**span_options).tap do |span|
    if block_given?
      begin
        return yield span
      ensure
        span.finish
      end
    end
  end
end