Cloud Trace API - Class Google::Cloud::Trace::Span (v0.44.0)

Reference documentation and code samples for the Cloud Trace API class Google::Cloud::Trace::Span.

Span represents a span in a trace record. Spans are contained in a trace and arranged in a forest. That is, each span may be a root span or have a parent span, and may have zero or more children.

Inherits

  • Object

Methods

.from_grpc

def self.from_grpc(span_proto, trace) -> Google::Cloud::Trace::Span

Create a new Span object from a TraceSpan protobuf and insert it into the given trace.

Parameters
  • span_proto (Google::Cloud::Trace::V1::Tracespan) — The span protobuf from the V1 gRPC Trace API.
  • trace (Google::Cloud::Trace::TraceRecord) — The trace object to contain the span.
Returns

#==

def ==(other) -> Boolean
Alias Of: #eql?

Standard value equality check for this object.

Parameter
  • other (Object)
Returns
  • (Boolean)

#children

def children() -> Array{TraceSpan}

Returns a list of children of this span.

Returns
  • (Array{TraceSpan}) — The children.

#create_span

def create_span(name, span_id: nil, kind: SpanKind::UNSPECIFIED, start_time: nil, end_time: nil, labels: {}) -> TraceSpan

Creates a new child span under this span.

Parameters
  • name (String) — The name of the span.
  • span_id (Integer) (defaults to: nil) — The numeric ID of the span, or nil to generate a new random unique ID. Optional (defaults to nil).
  • kind (SpanKind) (defaults to: SpanKind::UNSPECIFIED) — The kind of span. Optional.
  • start_time (Time) (defaults to: nil) — The starting timestamp, or nil if not yet specified. Optional (defaults to nil).
  • end_time (Time) (defaults to: nil) — The ending timestamp, or nil if not yet specified. Optional (defaults to nil).
  • labels (Hash{String=>String}) (defaults to: {}) — The span properties. Optional (defaults to empty).
Returns
  • (TraceSpan) — The created span.
Example 
require "google/cloud/trace"

trace_record = Google::Cloud::Trace::TraceRecord.new "my-project"
span = trace_record.create_span "root_span"
subspan = span.create_span "subspan"

#delete

def delete()

Deletes this span, and all descendant spans. After this completes, #exists? will return false.

#end_time

def end_time() -> Time, nil

The ending timestamp of this span in UTC, or nil if the ending timestamp has not yet been populated.

Returns
  • (Time, nil)

#end_time=

def end_time=(value) -> Time, nil

The ending timestamp of this span in UTC, or nil if the ending timestamp has not yet been populated.

Parameter
  • value (Time, nil)
Returns
  • (Time, nil)

#ensure_finished

def ensure_finished()

Sets the ending timestamp for this span to the current time, if it has not yet been set. Also ensures that all descendant spans have also been finished. Does nothing if the ending timestamp for this span is already set.

#ensure_started

def ensure_started()

Sets the starting timestamp for this span to the current time, if it has not yet been set. Also ensures that all ancestor spans have also been started. Does nothing if the starting timestamp for this span is already set.

#eql?

def eql?(other) -> Boolean
Aliases

Standard value equality check for this object.

Parameter
  • other (Object)
Returns
  • (Boolean)

#exists?

def exists?() -> Boolean

Returns true if this span exists. A span exists until it has been removed from its trace.

Returns
  • (Boolean)

#finish!

def finish!()

Sets the ending timestamp for this span to the current time. Asserts that the timestamp has not yet been set, and throws a RuntimeError if that is not the case. Also ensures that all descendant spans have also finished, and finishes them if not.

#in_span

def in_span(name, kind: SpanKind::UNSPECIFIED, labels: {}) -> TraceSpan

Creates a root span around the given block. Automatically populates the start and end timestamps. The span (with start time but not end time populated) is yielded to the block.

Parameters
  • name (String) — The name of the span.
  • kind (SpanKind) (defaults to: SpanKind::UNSPECIFIED) — The kind of span. Optional.
  • labels (Hash{String=>String}) (defaults to: {}) — The span properties. Optional (defaults to empty).
Returns
  • (TraceSpan) — The created span.
Example 
require "google/cloud/trace"

trace_record = Google::Cloud::Trace::TraceRecord.new "my-project"
trace_record.in_span "root_span" do |span|
  # Do stuff...
  span.in_span "subspan" do |subspan|
    # Do subspan stuff...
  end
  # Do stuff...
end

#kind

def kind() -> Google::Cloud::Trace::SpanKind

The kind of this span.

Returns

#kind=

def kind=(value) -> Google::Cloud::Trace::SpanKind

The kind of this span.

Parameter
Returns

#labels

def labels() -> Hash{String => String}

The properties of this span.

Returns
  • (Hash{String => String})

#move_under

def move_under(new_parent)

Moves this span under a new parent, which must be part of the same trace. The entire tree under this span moves with it.

Parameter
Example 
require "google/cloud/trace"

trace_record = Google::Cloud::Trace::TraceRecord.new "my-project"
root1 = trace_record.create_span "root_span_1"
root2 = trace_record.create_span "root_span_2"
subspan = root1.create_span "subspan"
subspan.move_under root2

#name

def name() -> String

The name of this span.

Returns
  • (String)

#name=

def name=(value) -> String

The name of this span.

Parameter
  • value (String)
Returns
  • (String)

#parent

def parent() -> Google::Cloud::Trace::Span, nil

The TraceSpan object representing this span's parent, or nil if this span is a root span.

Returns

#parent_span_id

def parent_span_id() -> Integer

The ID of the parent span, as an integer that may be zero if this is a true root span.

Note that it is possible for a span to be "orphaned", that is, to be a root span with a nonzero parent ID, indicating that parent has not (yet) been written. In that case, parent will return nil, but parent_span_id will have a value.

Returns
  • (Integer)

#span_id

def span_id() -> Integer

The numeric ID of this span.

Returns
  • (Integer)

#start!

def start!()

Sets the starting timestamp for this span to the current time. Asserts that the timestamp has not yet been set, and throws a RuntimeError if that is not the case. Also ensures that all ancestor spans have already started, and starts them if not.

#start_time

def start_time() -> Time, nil

The starting timestamp of this span in UTC, or nil if the starting timestamp has not yet been populated.

Returns
  • (Time, nil)

#start_time=

def start_time=(value) -> Time, nil

The starting timestamp of this span in UTC, or nil if the starting timestamp has not yet been populated.

Parameter
  • value (Time, nil)
Returns
  • (Time, nil)

#to_grpc

def to_grpc(default_parent_id = 0) -> Google::Cloud::Trace::V1::TraceSpan

Convert this Span object to an equivalent TraceSpan protobuf suitable for the V1 gRPC Trace API.

Parameter
  • default_parent_id (Integer) — The parent span ID to use if the span has no parent in the trace tree. Optional; defaults to 0.
Returns
  • (Google::Cloud::Trace::V1::TraceSpan) — The generated protobuf.

#trace

def trace() -> Google::Cloud::Trace::TraceRecord

The Trace object containing this span.

Returns

#trace_context

def trace_context() -> Stackdriver::Core::TraceContext

Returns the trace context in effect within this span.

Returns
  • (Stackdriver::Core::TraceContext)

#trace_id

def trace_id() -> String

Returns the trace ID for this span.

Returns
  • (String) — The trace ID string.