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

FORMAT_TEXT_MAP = 
1
FORMAT_BINARY = 
2
CARRIER_TRACER_STATE_PREFIX = 
'ot-tracer-'.freeze
CARRIER_BAGGAGE_PREFIX = 
'ot-baggage-'.freeze
DEFAULT_MAX_LOG_RECORDS = 
1000
MIN_MAX_LOG_RECORDS = 
1
DEFAULT_MAX_SPAN_RECORDS = 
1000
MIN_MAX_SPAN_RECORDS = 
1
DEFAULT_MIN_REPORTING_PERIOD_SECS = 
1.5
DEFAULT_MAX_REPORTING_PERIOD_SECS = 
30.0

Instance Attribute Summary collapse

Instance Method Summary collapse

Constructor Details

#initialize(component_name:, access_token: nil, transport: nil) ⇒ 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) (defaults to: nil) —

    How the data should be transported

Raises:

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



36
37
38
 
# File 'lib/lightstep/tracer.rb', line 36

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

Instance Attribute Details

#access_token ⇒ Object

Returns the value of attribute access_token.



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

def access_token
  @access_token
end

#guid ⇒ Object (readonly)

Returns the value of attribute guid.



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

def guid
  @guid
end

Instance Method Details

#disable(discard: true) ⇒ Object

Disables the tracer

Parameters:

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

    whether to discard queued data



147
148
149
150
151
 
# File 'lib/lightstep/tracer.rb', line 147

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

#enable ⇒ Object

Enables the tracer



141
142
143
 
# File 'lib/lightstep/tracer.rb', line 141

def enable
  @enabled = true
end

#enabled? ⇒ Boolean

Returns true if the tracer is enabled.

Returns:

  • (Boolean) —

    true if the tracer is enabled



135
136
137
138
 
# File 'lib/lightstep/tracer.rb', line 135

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

#extract(operation_name, format, carrier) ⇒ Span

Extract a span from a carrier

Parameters:

Returns:



121
122
123
124
125
126
127
128
129
130
131
132
 
# File 'lib/lightstep/tracer.rb', line 121

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

#finish_span(span) ⇒ Object

Internal use only.



160
161
162
163
164
165
166
167
168
169
 
# File 'lib/lightstep/tracer.rb', line 160

def finish_span(span)
  return unless enabled?
  @span_records.push(span.to_h)
  if @span_records.size > max_span_records
    @span_records.shift
    @dropped_spans.increment
    @dropped_span_logs.increment(span.logs_count + span.dropped_logs_count)
  end
  flush_if_needed
end

#flush ⇒ Object

Flush to the Transport



154
155
156
 
# File 'lib/lightstep/tracer.rb', line 154

def flush
  _flush_worker
end

#inject(span, format, carrier) ⇒ Object

Inject a span into the given carrier

Parameters:



105
106
107
108
109
110
111
112
113
114
 
# File 'lib/lightstep/tracer.rb', line 105

def inject(span, format, carrier)
  case format
  when LightStep::Tracer::FORMAT_TEXT_MAP
    inject_to_text_map(span, carrier)
  when LightStep::Tracer::FORMAT_BINARY
    warn 'Binary inject format not yet implemented'
  else
    warn 'Unknown inject format'
  end
end

#max_flush_period_micros ⇒ Object 



64
65
66
 
# File 'lib/lightstep/tracer.rb', line 64

def max_flush_period_micros
  @max_flush_period_micros ||= DEFAULT_MAX_REPORTING_PERIOD_SECS * 1E6
end

#max_log_records ⇒ Object 



40
41
42
 
# File 'lib/lightstep/tracer.rb', line 40

def max_log_records
  @max_log_records ||= DEFAULT_MAX_LOG_RECORDS
end

#max_log_records=(max) ⇒ Object 



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

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

#max_reporting_period_secs=(secs) ⇒ Object 



68
69
70
 
# File 'lib/lightstep/tracer.rb', line 68

def max_reporting_period_secs=(secs)
  @max_flush_period_micros = [DEFAULT_MAX_REPORTING_PERIOD_SECS, secs].min * 1E6
end

#max_span_records ⇒ Object 



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

def max_span_records
  @max_span_records ||= DEFAULT_MAX_SPAN_RECORDS
end

#max_span_records=(max) ⇒ Object 



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

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

#min_flush_period_micros ⇒ Object 



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

def min_flush_period_micros
  @min_flush_period_micros ||= DEFAULT_MIN_REPORTING_PERIOD_SECS * 1E6
end

#min_reporting_period_secs=(secs) ⇒ Object 



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

def min_reporting_period_secs=(secs)
  @min_flush_period_micros = [DEFAULT_MIN_REPORTING_PERIOD_SECS, secs].max * 1E6
end

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

Starts a new span.

Parameters:

  • operation_name (String) —

    the operation name for the Span

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

    Span to inherit from

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

    When the Span started, if not now

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

    tags for the span

Returns:



80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
 
# File 'lib/lightstep/tracer.rb', line 80

def start_span(operation_name, child_of: nil, start_time: nil, tags: nil)
  child_of_guid = nil
  trace_guid = nil
  if Span === child_of
    child_of_guid = child_of.guid
    trace_guid = child_of.trace_guid
  else
    trace_guid = LightStep.guid
  end

  Span.new(
    tracer: self,
    operation_name: operation_name,
    child_of_guid: child_of_guid,
    trace_guid: trace_guid,
    start_micros: start_time.nil? ? LightStep.micros(Time.now) : LightStep.micros(start_time),
    tags: tags,
    max_log_records: max_log_records
  )
end