Class: OpenTracing::Tracer

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

Overview

Tracer is the entry point API between instrumentation code and the tracing implementation.

This implementation both defines the public Tracer API, and provides a default no-op behavior.

Instance Method Summary collapse

Instance Method Details

#active_span ⇒ Span?

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

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.



18
19
20
21
 
# File 'lib/opentracing/tracer.rb', line 18

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

#extract(format, carrier) ⇒ SpanContext?

Extract a SpanContext in the given format from the given carrier.

Parameters:

Returns:

  • (SpanContext, nil) —

    the extracted SpanContext or nil if none could be found



116
117
118
119
120
121
122
123
124
 
# File 'lib/opentracing/tracer.rb', line 116

def extract(format, carrier)
  case format
  when OpenTracing::FORMAT_TEXT_MAP, OpenTracing::FORMAT_BINARY, OpenTracing::FORMAT_RACK
    return SpanContext::NOOP_INSTANCE
  else
    warn 'Unknown extract format'
    nil
  end
end

#inject(span_context, format, carrier) ⇒ Object

Inject a SpanContext into the given carrier

Parameters:



102
103
104
105
106
107
108
109
 
# File 'lib/opentracing/tracer.rb', line 102

def inject(span_context, format, carrier)
  case format
  when OpenTracing::FORMAT_TEXT_MAP, OpenTracing::FORMAT_BINARY, OpenTracing::FORMAT_RACK
    return nil
  else
    warn 'Unknown inject format'
  end
end

#scope_manager ⇒ ScopeManager

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

Returns:

  • (ScopeManager) —

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



11
12
13
 
# File 'lib/opentracing/tracer.rb', line 11

def scope_manager
  ScopeManager::NOOP_INSTANCE
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 the Tracer’s 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 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



51
52
53
54
55
56
57
58
59
60
61
 
# File 'lib/opentracing/tracer.rb', line 51

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)
  Scope::NOOP_INSTANCE.tap do |scope|
    return yield scope if block_given?
  end
end

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

Like #start_active_span, but the returned Span has not been registered via the ScopeManager.

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.

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



86
87
88
89
90
91
92
93
94
95
 
# File 'lib/opentracing/tracer.rb', line 86

def start_span(operation_name,
               child_of: nil,
               references: nil,
               start_time: Time.now,
               tags: nil,
               ignore_active_scope: false)
  Span::NOOP_INSTANCE.tap do |span|
    return yield span if block_given?
  end
end