Class: OpenTelemetry::Trace::Span

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

Overview

Span represents a single operation within a trace. Spans can be nested to form a trace tree. Often, a trace contains a root span that describes the end-to-end latency and, optionally, one or more sub-spans for its sub-operations.

Once Span is created - Span operations can be used to add additional properties to it like attributes, links, events, name and resulting status. Span cannot be used to retrieve these properties. This prevents the mis-use of spans as an in-process information propagation mechanism.

Span must be ended by calling #finish.

Constant Summary collapse

INVALID = 
new(span_context: SpanContext::INVALID)

Instance Attribute Summary collapse

Instance Method Summary collapse

Constructor Details

#initialize(span_context: nil) ⇒ 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.

Spans must be created using Tracer. This is for internal use only.



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

def initialize(span_context: nil)
  @context = span_context || SpanContext.new
end

Instance Attribute Details

#context ⇒ SpanContext (readonly)

Retrieve the spans SpanContext

The returned value may be used even after the Span is finished.

Returns:



27
28
29
 
# File 'lib/opentelemetry/trace/span.rb', line 27

def context
  @context
end

Instance Method Details

#add_attributes(attributes) ⇒ self

Add attributes

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

Parameters:

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

    Values must be non-nil and (array of) string, boolean or numeric type. Array values must not contain nil elements and all elements must be of the same basic type (string, numeric, boolean).

Returns:

  • (self) —

    returns itself



77
78
79
 
# File 'lib/opentelemetry/trace/span.rb', line 77

def add_attributes(attributes)
  self
end

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

Add an event to a OpenTelemetry::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 (array of) string, boolean or numeric type.

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

    Optional timestamp for the event.

Returns:

  • (self) —

    returns itself



122
123
124
 
# File 'lib/opentelemetry/trace/span.rb', line 122

def add_event(name, attributes: nil, timestamp: nil)
  self
end

#add_link(link) ⇒ self

Add a link to a OpenTelemetry::Trace::Span.

Adding links at span creation using the links option is preferred to calling add_link later, because head sampling decisions can only consider information present during span creation.

Example:

span.add_link(OpenTelemetry::Trace::Link.new(span_to_link_from.context))

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

Parameters:

Returns:

  • (self) —

    returns itself



99
100
101
 
# File 'lib/opentelemetry/trace/span.rb', line 99

def add_link(link)
  self
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.

Parameters:

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

    optional end timestamp for the span.

Returns:

  • (self) —

    returns itself



176
177
178
 
# File 'lib/opentelemetry/trace/span.rb', line 176

def finish(end_timestamp: nil)
  self
end

#name=(new_name) ⇒ void

This method returns an undefined value.

Updates the Span name

Upon this update, any sampling behavior based on Span name will depend on the implementation.

Parameters:

  • new_name (String) —

    The new operation name, which supersedes whatever was passed in when the Span was started



160
 
# File 'lib/opentelemetry/trace/span.rb', line 160

def name=(new_name); end

#record_exception(exception, attributes: nil) ⇒ 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 recorded

  • 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 (array of) string, boolean or numeric type.



136
 
# File 'lib/opentelemetry/trace/span.rb', line 136

def record_exception(exception, attributes: nil); end

#recording? ⇒ Boolean

Return whether this span is recording.

Returns:

  • (Boolean) —

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

    set_attribute.



41
42
43
 
# File 'lib/opentelemetry/trace/span.rb', line 41

def recording?
  false
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>) —

    Values must be non-nil and (array of) string, boolean or numeric type. Array values must not contain nil elements and all elements must be of the same basic type (string, numeric, boolean).

Returns:

  • (self) —

    returns itself



59
60
61
 
# File 'lib/opentelemetry/trace/span.rb', line 59

def set_attribute(key, value)
  self
end

#status=(status) ⇒ void

This method returns an undefined value.

Sets the Status to the Span

If used, this will override the default Span status. Default status is unset.

Only the value of the last call will be recorded, and implementations are free to ignore previous calls.

Parameters:

  • status (Status) —

    The new status, which overrides the default Span status, which is OK.



149
 
# File 'lib/opentelemetry/trace/span.rb', line 149

def status=(status); end