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_event(name: nil, attributes: nil, timestamp: nil) ⇒ self

Add an Event to a OpenTelemetry::Trace::Span. This can be accomplished eagerly or lazily. Lazy evaluation is useful when the event attributes are expensive to build and where the cost can be avoided for an unsampled OpenTelemetry::Trace::Span.

Eager example:

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

Lazy example:

span.add_event { tracer.create_event(name: 'event', attributes: {'eager' => false}) }

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

Parameters:

  • name (optional String) (defaults to: nil) —

    Optional name of the event. This is required if a block is not given.

  • attributes (optional Hash<String, Object>) (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. This argument should only be used when passing in a name.

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

    Optional timestamp for the event. This argument should only be used when passing in a name.

Returns:

  • (self) —

    returns itself



88
89
90
 
# File 'lib/opentelemetry/trace/span.rb', line 88

def add_event(name: nil, attributes: nil, timestamp: nil)
  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



130
131
132
 
# File 'lib/opentelemetry/trace/span.rb', line 130

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



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

def name=(new_name); 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)

Returns:

  • (self) —

    returns itself



56
57
58
 
# File 'lib/opentelemetry/trace/span.rb', line 56

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 is OK.

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.



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

def status=(status); end