Class: SplunkTracing::Tracer

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

Direct Known Subclasses

GlobalTracer

Defined Under Namespace

Classes: ConfigurationError, Error

Instance Attribute Summary collapse

Instance Method Summary collapse

Constructor Details

#initialize(component_name:, access_token: nil, transport: nil, tags: {}) ⇒ 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 SplunkTracing

  • transport (SplunkTracing::Transport) (defaults to: nil) —

    How the data should be transported

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

    Tracer-level tags

Raises:

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



27
28
29
 
# File 'lib/splunktracing/tracer.rb', line 27

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

Instance Attribute Details

#access_token ⇒ Object (readonly)

Returns the value of attribute access_token.



17
18
19
 
# File 'lib/splunktracing/tracer.rb', line 17

def access_token
  @access_token
end

#guid ⇒ Object (readonly)

Returns the value of attribute guid.



17
18
19
 
# File 'lib/splunktracing/tracer.rb', line 17

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.



123
124
125
126
 
# File 'lib/splunktracing/tracer.rb', line 123

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



208
209
210
211
212
 
# File 'lib/splunktracing/tracer.rb', line 208

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

#enable ⇒ Object

Enables the tracer



202
203
204
 
# File 'lib/splunktracing/tracer.rb', line 202

def enable
  @enabled = true
end

#enabled? ⇒ Boolean

Returns true if the tracer is enabled.

Returns:

  • (Boolean) —

    true if the tracer is enabled



196
197
198
199
 
# File 'lib/splunktracing/tracer.rb', line 196

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



180
181
182
183
184
185
186
187
188
189
190
191
192
193
 
# File 'lib/splunktracing/tracer.rb', line 180

def extract(format, carrier)
  case format
  when OpenTracing::FORMAT_TEXT_MAP
    extract_from_text_map(carrier)
  when OpenTracing::FORMAT_BINARY
    warn 'Binary join format not yet implemented'
    nil
  when OpenTracing::FORMAT_RACK
    extract_from_rack(carrier)
  else
    warn 'Unknown join format'
    nil
  end
end

#finish_span(span) ⇒ Object

Internal use only.



222
223
224
225
 
# File 'lib/splunktracing/tracer.rb', line 222

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

#flush ⇒ Object

Flush to the Transport



215
216
217
218
 
# File 'lib/splunktracing/tracer.rb', line 215

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`



163
164
165
166
167
168
169
170
171
172
173
174
 
# File 'lib/splunktracing/tracer.rb', line 163

def inject(span_context, format, carrier)
  case format
  when OpenTracing::FORMAT_TEXT_MAP
    inject_to_text_map(span_context, carrier)
  when OpenTracing::FORMAT_BINARY
    warn 'Binary inject format not yet implemented'
  when OpenTracing::FORMAT_RACK
    inject_to_rack(span_context, carrier)
  else
    warn 'Unknown inject format'
  end
end

#max_log_records ⇒ Object 



31
32
33
 
# File 'lib/splunktracing/tracer.rb', line 31

def max_log_records
  @max_log_records ||= DEFAULT_MAX_LOG_RECORDS
end

#max_log_records=(max) ⇒ Object 



35
36
37
 
# File 'lib/splunktracing/tracer.rb', line 35

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

#max_span_records ⇒ Object 



39
40
41
 
# File 'lib/splunktracing/tracer.rb', line 39

def max_span_records
  @max_span_records ||= DEFAULT_MAX_SPAN_RECORDS
end

#max_span_records=(max) ⇒ Object 



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

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.



50
51
52
 
# File 'lib/splunktracing/tracer.rb', line 50

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.



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

def scope_manager
  @scope_manager ||= SplunkTracing::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

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 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) —

    The newly-started and activated Scope



90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
 
# File 'lib/splunktracing/tracer.rb', line 90

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?
      yield scope
      scope.close
    end
  end
end

#start_span(operation_name, child_of: nil, references: nil, start_time: nil, tags: nil, ignore_active_scope: false) ⇒ Span

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.

Returns:



142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
 
# File 'lib/splunktracing/tracer.rb', line 142

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.new(
    tracer: self,
    operation_name: operation_name,
    child_of: child_of,
    references: references,
    start_micros: start_time.nil? ? SplunkTracing.micros(Time.now) : SplunkTracing.micros(start_time),
    tags: tags,
    max_log_records: max_log_records,
  )
end