Class: OpenTelemetry::SDK::Trace::Span

Inherits:
Trace::Span
  • Object
show all
Defined in:
lib/opentelemetry/sdk/trace/span.rb

Overview

Implementation of Trace::Span that records trace events.

This implementation includes reader methods intended to allow access to internal state by SpanProcessors (see NoopSpanProcessor for the interface). Instrumentation should use the API provided by Trace::Span and should consider Span to be write-only.

rubocop:disable Metrics/ClassLength

Instance Attribute Summary collapse

Instance Method Summary collapse

Constructor Details

#initialize(context, parent_context, name, kind, parent_span_id, trace_config, span_processor, attributes, links, start_timestamp, resource, instrumentation_library) ⇒ Span

This method is part of a private API. You should avoid using this method if possible, as it may be removed or be changed in the future.

Returns a new instance of Span.



244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
 
# File 'lib/opentelemetry/sdk/trace/span.rb', line 244

def initialize(context, parent_context, name, kind, parent_span_id, trace_config, span_processor, attributes, links, start_timestamp, resource, instrumentation_library) # rubocop:disable Metrics/AbcSize
  super(span_context: context)
  @mutex = Mutex.new
  @name = name
  @kind = kind
  @parent_span_id = parent_span_id.freeze || OpenTelemetry::Trace::INVALID_SPAN_ID
  @trace_config = trace_config
  @span_processor = span_processor
  @resource = resource
  @instrumentation_library = instrumentation_library
  @ended = false
  @status = DEFAULT_STATUS
  @total_recorded_events = 0
  @total_recorded_links = links&.size || 0
  @total_recorded_attributes = attributes&.size || 0
  @start_timestamp = start_timestamp
  @end_timestamp = nil
  @attributes = attributes.nil? ? nil : Hash[attributes] # We need a mutable copy of attributes.
  trim_span_attributes(@attributes)
  @events = nil
  @links = trim_links(links, trace_config.max_links_count, trace_config.max_attributes_per_link)
  @span_processor.on_start(self, parent_context)
end

Instance Attribute Details

#end_timestamp ⇒ Object (readonly)

The following readers are intended for the use of SpanProcessors and should not be considered part of the public interface for instrumentation.



25
26
27
 
# File 'lib/opentelemetry/sdk/trace/span.rb', line 25

def end_timestamp
  @end_timestamp
end

#instrumentation_library ⇒ Object (readonly)

The following readers are intended for the use of SpanProcessors and should not be considered part of the public interface for instrumentation.



25
26
27
 
# File 'lib/opentelemetry/sdk/trace/span.rb', line 25

def instrumentation_library
  @instrumentation_library
end

#kind ⇒ Object (readonly)

The following readers are intended for the use of SpanProcessors and should not be considered part of the public interface for instrumentation.



25
26
27
 
# File 'lib/opentelemetry/sdk/trace/span.rb', line 25

def kind
  @kind
end

#links ⇒ Object (readonly)

The following readers are intended for the use of SpanProcessors and should not be considered part of the public interface for instrumentation.



25
26
27
 
# File 'lib/opentelemetry/sdk/trace/span.rb', line 25

def links
  @links
end

#name ⇒ Object

The following readers are intended for the use of SpanProcessors and should not be considered part of the public interface for instrumentation.



25
26
27
 
# File 'lib/opentelemetry/sdk/trace/span.rb', line 25

def name
  @name
end

#parent_span_id ⇒ Object (readonly)

The following readers are intended for the use of SpanProcessors and should not be considered part of the public interface for instrumentation.



25
26
27
 
# File 'lib/opentelemetry/sdk/trace/span.rb', line 25

def parent_span_id
  @parent_span_id
end

#resource ⇒ Object (readonly)

The following readers are intended for the use of SpanProcessors and should not be considered part of the public interface for instrumentation.



25
26
27
 
# File 'lib/opentelemetry/sdk/trace/span.rb', line 25

def resource
  @resource
end

#start_timestamp ⇒ Object (readonly)

The following readers are intended for the use of SpanProcessors and should not be considered part of the public interface for instrumentation.



25
26
27
 
# File 'lib/opentelemetry/sdk/trace/span.rb', line 25

def start_timestamp
  @start_timestamp
end

#status ⇒ Object

The following readers are intended for the use of SpanProcessors and should not be considered part of the public interface for instrumentation.



25
26
27
 
# File 'lib/opentelemetry/sdk/trace/span.rb', line 25

def status
  @status
end

Instance Method Details

#add_event(name, attributes: nil, timestamp: nil) ⇒ self

Add an Event to a OpenTelemetry::SDK::Trace::Span.

Example:

span.add_event('event', attributes: => true)

Note that the OpenTelemetry project documents certain “standard event names and keys” which have prescribed semantic meanings.

Parameters:

  • name (String) —

    Name of the event.

  • attributes (optional Hash{String => String, Numeric, Boolean, Array<String, Numeric, Boolean>}) (defaults to: nil) —

    One or more key:value pairs, where the keys must be strings and the values may be string, boolean or numeric type.

  • timestamp (optional Time) (defaults to: nil) —

    Optional timestamp for the event.

Returns:

  • (self) —

    returns itself



103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
 
# File 'lib/opentelemetry/sdk/trace/span.rb', line 103

def add_event(name, attributes: nil, timestamp: nil)
  super
  event = Event.new(name: name, attributes: attributes, timestamp: timestamp || Time.now)

  @mutex.synchronize do
    if @ended
      OpenTelemetry.logger.warn('Calling add_event on an ended Span.')
    else
      @events ||= []
      @events = append_event(@events, event)
      @total_recorded_events += 1
    end
  end
  self
end

#attributes ⇒ Hash{String => String, Numeric, Boolean, Array<String, Numeric, Boolean>}

Return a frozen copy of the current attributes. This is intended for use of SpanProcessors and should not be considered part of the public interface for instrumentation.

Returns:

  • (Hash{String => String, Numeric, Boolean, Array<String, Numeric, Boolean>}) —

    may be nil.



32
33
34
35
36
 
# File 'lib/opentelemetry/sdk/trace/span.rb', line 32

def attributes
  # Don't bother synchronizing. Access by SpanProcessors is expected to
  # be serialized.
  @attributes&.clone.freeze
end

#events ⇒ Array<Event>

Return a frozen copy of the current events. This is intended for use of SpanProcessors and should not be considered part of the public interface for instrumentation.

Returns:

  • (Array<Event>) —

    may be nil.



43
44
45
46
47
 
# File 'lib/opentelemetry/sdk/trace/span.rb', line 43

def events
  # Don't bother synchronizing. Access by SpanProcessors is expected to
  # be serialized.
  @events&.clone.freeze
end

#finish(end_timestamp: nil) ⇒ self

Finishes the Span

Implementations MUST ignore all subsequent calls to #finish (there might be exceptions when Tracer is streaming event and has no mutable state associated with the Span).

Call to #finish MUST not have any effects on child spans. Those may still be running and can be ended later.

This API MUST be non-blocking*.

(*) not actually non-blocking. In particular, it synchronizes on an internal mutex, which will typically be uncontended, and Export::BatchSpanProcessor will also synchronize on a mutex, if that processor is used.

Parameters:

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

    optional end timestamp for the span.

Returns:

  • (self) —

    returns itself



195
196
197
198
199
200
201
202
203
204
205
206
207
208
 
# File 'lib/opentelemetry/sdk/trace/span.rb', line 195

def finish(end_timestamp: nil)
  @mutex.synchronize do
    if @ended
      OpenTelemetry.logger.warn('Calling finish on an ended Span.')
      return self
    end
    @end_timestamp = end_timestamp || Time.now
    @attributes.freeze
    @events.freeze
    @ended = true
  end
  @span_processor.on_finish(self)
  self
end

#record_exception(exception) ⇒ void

This method returns an undefined value.

Record an exception during the execution of this span. Multiple exceptions can be recorded on a span.

Parameters:

  • exception (Exception) —

    The exception to be recorded



125
126
127
128
129
130
131
132
 
# File 'lib/opentelemetry/sdk/trace/span.rb', line 125

def record_exception(exception)
  add_event('exception',
            attributes: {
              'exception.type' => exception.class.to_s,
              'exception.message' => exception.message,
              'exception.stacktrace' => exception.full_message(highlight: false, order: :top)
            })
end

#recording? ⇒ Boolean

Return the flag whether this span is recording events

Returns:

  • (Boolean) —

    true if this Span is active and recording information like events with the #add_event operation and attributes using

    set_attribute.



54
55
56
 
# File 'lib/opentelemetry/sdk/trace/span.rb', line 54

def recording?
  !@ended
end

#set_attribute(key, value) ⇒ self Also known as: []=

Set attribute

Note that the OpenTelemetry project documents certain “standard attributes” that have prescribed semantic meanings.

Parameters:

  • key (String)
  • value (String, Boolean, Numeric, Array<String, Numeric, Boolean>)

Returns:

  • (self) —

    returns itself



69
70
71
72
73
74
75
76
77
78
79
80
81
82
 
# File 'lib/opentelemetry/sdk/trace/span.rb', line 69

def set_attribute(key, value)
  super
  @mutex.synchronize do
    if @ended
      OpenTelemetry.logger.warn('Calling set_attribute on an ended Span.')
    else
      @attributes ||= {}
      @attributes[key] = value
      trim_span_attributes(@attributes)
      @total_recorded_attributes += 1
    end
  end
  self
end

#to_span_data ⇒ SpanData

This method is part of a private API. You should avoid using this method if possible, as it may be removed or be changed in the future.

Returns a SpanData containing a snapshot of the Span fields. It is assumed that the Span has been finished, and that no further modifications will be made to the Span.

This method should be called only from a SpanProcessor prior to calling the SpanExporter.

Returns:



220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
 
# File 'lib/opentelemetry/sdk/trace/span.rb', line 220

def to_span_data
  SpanData.new(
    @name,
    @kind,
    @status,
    @parent_span_id,
    @total_recorded_attributes,
    @total_recorded_events,
    @total_recorded_links,
    @start_timestamp,
    @end_timestamp,
    @attributes,
    @links,
    @events,
    @resource,
    @instrumentation_library,
    context.span_id,
    context.trace_id,
    context.trace_flags,
    context.tracestate
  )
end