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.

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.



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



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 



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



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



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.



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.

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.



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.

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.



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