Cloud Trace API - Class Google::Cloud::Trace::Span (v0.45.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 ina trace and arranged in a forest. That is, each span may be a root spanor have a parent span, and may have zero or more children.

Inherits

  • Object

Methods

.from_grpc

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

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

Returns

#==

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

Standard value equality check for this object.

Parameter
  • other (Object)
Returns
  • (Boolean)

#children

defchildren()->Array{TraceSpan}

Returns a list of children of this span.

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

#create_span

defcreate_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 togenerate 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 yetspecified. Optional (defaults to nil).
  • end_time (Time)(defaults to: nil) — The ending timestamp, or nil if not yetspecified. 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

defdelete()

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

#end_time

defend_time()->Time,nil

The ending timestamp of this span in UTC, ornil if theending timestamp has not yet been populated.

Returns
  • (Time, nil)

#end_time=

defend_time=(value)->Time,nil

The ending timestamp of this span in UTC, ornil if theending timestamp has not yet been populated.

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

#ensure_finished

defensure_finished()

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

#ensure_started

defensure_started()

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

#eql?

defeql?(other)->Boolean
Aliases

Standard value equality check for this object.

Parameter
  • other (Object)
Returns
  • (Boolean)

#exists?

defexists?()->Boolean

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

Returns
  • (Boolean)

#finish!

deffinish!()

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

#in_span

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

Creates a root span around the given block. Automatically populatesthe start and end timestamps. The span (with start time but not endtime 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

defkind()->Google::Cloud::Trace::SpanKind

The kind of this span.

#kind=

defkind=(value)->Google::Cloud::Trace::SpanKind

The kind of this span.

#labels

deflabels()->Hash{String=>String}

The properties of this span.

Returns
  • (Hash{String => String})

#move_under

defmove_under(new_parent)

Moves this span under a new parent, which must be part of the sametrace. 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_underroot2

#name

defname()->String

The name of this span.

Returns
  • (String)

#name=

defname=(value)->String

The name of this span.

Parameter
  • value (String)
Returns
  • (String)

#parent

defparent()->Google::Cloud::Trace::Span,nil

The TraceSpan object representing this span's parent, ornil ifthis span is a root span.

#parent_span_id

defparent_span_id()->Integer

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

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

Returns
  • (Integer)

#span_id

defspan_id()->Integer

The numeric ID of this span.

Returns
  • (Integer)

#start!

defstart!()

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

#start_time

defstart_time()->Time,nil

The starting timestamp of this span in UTC, ornil if thestarting timestamp has not yet been populated.

Returns
  • (Time, nil)

#start_time=

defstart_time=(value)->Time,nil

The starting timestamp of this span in UTC, ornil if thestarting timestamp has not yet been populated.

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

#to_grpc

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

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

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

#trace

deftrace()->Google::Cloud::Trace::TraceRecord

The Trace object containing this span.

#trace_context

deftrace_context()->Stackdriver::Core::TraceContext

Returns the trace context in effect within this span.

Returns
  • (Stackdriver::Core::TraceContext)

#trace_id

deftrace_id()->String

Returns the trace ID for this span.

Returns
  • (String) — The trace ID string.

Except as otherwise noted, the content of this page is licensed under theCreative Commons Attribution 4.0 License, and code samples are licensed under theApache 2.0 License. For details, see theGoogle Developers Site Policies. Java is a registered trademark of Oracle and/or its affiliates.

Last updated 2025-10-30 UTC.