class OpenTelemetry::Trace::Span

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 {Tracer#start_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}.

Constants

INVALID

Attributes

context[R]

Retrieve the spans SpanContext

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

@return [SpanContext]

Public Class Methods

new(span_context: nil) click to toggle source

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

@api private

# File lib/opentelemetry/trace/span.rb, line 32
def initialize(span_context: nil)
  @context = span_context || SpanContext.new
end

Public Instance Methods

[]=(key, value)
Alias for: set_attribute
add_attributes(attributes) click to toggle source

Add attributes

Note that the OpenTelemetry project {github.com/open-telemetry/opentelemetry-specification/blob/master/specification/data-semantic-conventions.md documents} certain “standard attributes” that have prescribed semantic meanings.

@param [Hash{String => String, Numeric, Boolean, Array<String, Numeric, Boolean>}] attributes

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

@return [self] returns itself

# File lib/opentelemetry/trace/span.rb, line 77
def add_attributes(attributes)
  self
end
add_event(name, attributes: nil, timestamp: nil) click to toggle source

Add an event to a {Span}.

Example:

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

Note that the OpenTelemetry project {github.com/open-telemetry/opentelemetry-specification/blob/master/specification/data-semantic-conventions.md documents} certain “standard event names and keys” which have prescribed semantic meanings.

@param [String] name Name of the event. @param [optional Hash{String => String, Numeric, Boolean, Array<String, Numeric, Boolean>}]

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

@param [optional Time] timestamp Optional timestamp for the event.

@return [self] returns itself

# File lib/opentelemetry/trace/span.rb, line 100
def add_event(name, attributes: nil, timestamp: nil)
  self
end
finish(end_timestamp: nil) click to toggle source

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.

@param [Time] end_timestamp optional end timestamp for the span.

@return [self] returns itself

# File lib/opentelemetry/trace/span.rb, line 154
def finish(end_timestamp: nil)
  self
end
name=(new_name) click to toggle source

Updates the Span name

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

@param [String] new_name The new operation name, which supersedes

whatever was passed in when the Span was started

@return [void]

# File lib/opentelemetry/trace/span.rb, line 138
def name=(new_name); end
record_exception(exception, attributes: nil) click to toggle source

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

@param [Exception] exception The exception to recorded @param [optional Hash{String => String, Numeric, Boolean, Array<String, Numeric, Boolean>}]

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

@return [void]

# File lib/opentelemetry/trace/span.rb, line 114
def record_exception(exception, attributes: nil); end
recording?() click to toggle source

Return whether this span is recording.

@return [Boolean] true if this Span is active and recording information

like events with the #add_event operation and attributes using
#set_attribute.
# File lib/opentelemetry/trace/span.rb, line 41
def recording?
  false
end
set_attribute(key, value) click to toggle source

Set attribute

Note that the OpenTelemetry project {github.com/open-telemetry/opentelemetry-specification/blob/master/specification/data-semantic-conventions.md documents} certain “standard attributes” that have prescribed semantic meanings.

@param [String] key @param [String, Boolean, Numeric, Array<String, Numeric, Boolean>] value

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

@return [self] returns itself

# File lib/opentelemetry/trace/span.rb, line 59
def set_attribute(key, value)
  self
end
Also aliased as: []=
status=(status) click to toggle source

Sets the Status to the Span

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

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

@param [Status] status The new status, which overrides the default Span

status, which is OK.

@return [void]

# File lib/opentelemetry/trace/span.rb, line 127
def status=(status); end