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.
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, ornilif the
ending timestamp has not yet been populated.
Returns
(Time, nil)
#end_time=
defend_time=(value)->Time,nil
The ending timestamp of this span in UTC, ornilif the
ending 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, 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
defensure_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.
Returns true if this span exists. A span exists until it has been
removed 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 a
RuntimeError if that is not the case.
Also ensures that all descendant spans have also finished, and
finishes them if not.
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
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,parentwill return nil, butparent_span_idwill 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 a
RuntimeError if that is not the case.
Also ensures that all ancestor spans have already started, and
starts them if not.
#start_time
defstart_time()->Time,nil
The starting timestamp of this span in UTC, ornilif the
starting timestamp has not yet been populated.
Returns
(Time, nil)
#start_time=
defstart_time=(value)->Time,nil
The starting timestamp of this span in UTC, ornilif the
starting timestamp has not yet been populated.
[[["Easy to understand","easyToUnderstand","thumb-up"],["Solved my problem","solvedMyProblem","thumb-up"],["Other","otherUp","thumb-up"]],[["Hard to understand","hardToUnderstand","thumb-down"],["Incorrect information or sample code","incorrectInformationOrSampleCode","thumb-down"],["Missing the information/samples I need","missingTheInformationSamplesINeed","thumb-down"],["Other","otherDown","thumb-down"]],["Last updated 2025-09-04 UTC."],[],[],null,["# Cloud Trace API - Class Google::Cloud::Trace::Span (v0.45.0)\n\nVersion latestkeyboard_arrow_down\n\n- [0.45.0 (latest)](/ruby/docs/reference/google-cloud-trace/latest/Google-Cloud-Trace-Span)\n- [0.44.1](/ruby/docs/reference/google-cloud-trace/0.44.1/Google-Cloud-Trace-Span)\n- [0.43.0](/ruby/docs/reference/google-cloud-trace/0.43.0/Google-Cloud-Trace-Span)\n- [0.42.2](/ruby/docs/reference/google-cloud-trace/0.42.2/Google-Cloud-Trace-Span)\n- [0.41.4](/ruby/docs/reference/google-cloud-trace/0.41.4/Google-Cloud-Trace-Span) \nReference documentation and code samples for the Cloud Trace API class Google::Cloud::Trace::Span.\n\nSpan represents a span in a trace record. Spans are contained in\na trace and arranged in a forest. That is, each span may be a root span\nor have a parent span, and may have zero or more children. \n\nInherits\n--------\n\n- Object\n\nMethods\n-------\n\n### .from_grpc\n\n def self.from_grpc(span_proto, trace) -\u003e Google::Cloud::Trace::Span\n\nCreate a new Span object from a TraceSpan protobuf and insert it\ninto the given trace. \n**Parameters**\n\n- **span_proto** (Google::Cloud::Trace::V1::Tracespan) --- The span protobuf from the V1 gRPC Trace API.\n- **trace** ([Google::Cloud::Trace::TraceRecord](./Google-Cloud-Trace-TraceRecord)) --- The trace object to contain the span. \n**Returns**\n\n- ([Google::Cloud::Trace::Span](./Google-Cloud-Trace-Span)) --- A corresponding Span object.\n\n### #==\n\n def ==(other) -\u003e Boolean\n\n**Alias Of** : [#eql?](./Google-Cloud-Trace-Span#Google__Cloud__Trace__Span_eql?_instance_) \nStandard value equality check for this object. \n**Parameter**\n\n- **other** (Object) \n**Returns**\n\n- (Boolean)\n\n### #children\n\n def children() -\u003e Array{TraceSpan}\n\nReturns a list of children of this span. \n**Returns**\n\n- (Array{TraceSpan}) --- The children.\n\n### #create_span\n\n def create_span(name, span_id: nil, kind: SpanKind::UNSPECIFIED, start_time: nil, end_time: nil, labels: {}) -\u003e TraceSpan\n\nCreates a new child span under this span. \n**Parameters**\n\n- **name** (String) --- The name of the span.\n- **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).\n- **kind** ([SpanKind](./Google-Cloud-Trace-SpanKind)) *(defaults to: SpanKind::UNSPECIFIED)* --- The kind of span. Optional.\n- **start_time** (Time) *(defaults to: nil)* --- The starting timestamp, or nil if not yet specified. Optional (defaults to nil).\n- **end_time** (Time) *(defaults to: nil)* --- The ending timestamp, or nil if not yet specified. Optional (defaults to nil).\n- **labels** (Hash{String=\\\u003eString}) *(defaults to: {})* --- The span properties. Optional (defaults to empty). \n**Returns**\n\n- (TraceSpan) --- The created span.\n**Example** \n\n```ruby\nrequire \"google/cloud/trace\"\n\ntrace_record = Google::Cloud::Trace::TraceRecord.new \"my-project\"\nspan = trace_record.create_span \"root_span\"\nsubspan = span.create_span \"subspan\"\n```\n\n### #delete\n\n def delete()\n\nDeletes this span, and all descendant spans. After this completes,\n[#exists?](/ruby/docs/reference/google-cloud-trace/latest/Google-Cloud-Trace-Span#Google__Cloud__Trace__Span_exists__instance_ \"Google::Cloud::Trace::Span#exists? (method)\") will return `false`.\n\n### #end_time\n\n def end_time() -\u003e Time, nil\n\nThe ending timestamp of this span in UTC, or `nil` if the\nending timestamp has not yet been populated. \n**Returns**\n\n- (Time, nil)\n\n### #end_time=\n\n def end_time=(value) -\u003e Time, nil\n\nThe ending timestamp of this span in UTC, or `nil` if the\nending timestamp has not yet been populated. \n**Parameter**\n\n- **value** (Time, nil) \n**Returns**\n\n- (Time, nil)\n\n### #ensure_finished\n\n def ensure_finished()\n\nSets the ending timestamp for this span to the current time, if\nit has not yet been set. Also ensures that all descendant spans have\nalso been finished.\nDoes nothing if the ending timestamp for this span is already set.\n\n### #ensure_started\n\n def ensure_started()\n\nSets the starting timestamp for this span to the current time, if\nit has not yet been set. Also ensures that all ancestor spans have\nalso been started.\nDoes nothing if the starting timestamp for this span is already set.\n\n### #eql?\n\n def eql?(other) -\u003e Boolean\n\n**Aliases**\n\n- [#==](./Google-Cloud-Trace-Span#Google__Cloud__Trace__Span_==_instance_) \nStandard value equality check for this object. \n**Parameter**\n\n- **other** (Object) \n**Returns**\n\n- (Boolean)\n\n### #exists?\n\n def exists?() -\u003e Boolean\n\nReturns true if this span exists. A span exists until it has been\nremoved from its trace. \n**Returns**\n\n- (Boolean)\n\n### #finish!\n\n def finish!()\n\nSets the ending timestamp for this span to the current time.\nAsserts that the timestamp has not yet been set, and throws a\nRuntimeError if that is not the case.\nAlso ensures that all descendant spans have also finished, and\nfinishes them if not.\n\n### #in_span\n\n def in_span(name, kind: SpanKind::UNSPECIFIED, labels: {}) -\u003e TraceSpan\n\nCreates a root span around the given block. Automatically populates\nthe start and end timestamps. The span (with start time but not end\ntime populated) is yielded to the block. \n**Parameters**\n\n- **name** (String) --- The name of the span.\n- **kind** ([SpanKind](./Google-Cloud-Trace-SpanKind)) *(defaults to: SpanKind::UNSPECIFIED)* --- The kind of span. Optional.\n- **labels** (Hash{String=\\\u003eString}) *(defaults to: {})* --- The span properties. Optional (defaults to empty). \n**Returns**\n\n- (TraceSpan) --- The created span.\n**Example** \n\n```ruby\nrequire \"google/cloud/trace\"\n\ntrace_record = Google::Cloud::Trace::TraceRecord.new \"my-project\"\ntrace_record.in_span \"root_span\" do |span|\n # Do stuff...\n span.in_span \"subspan\" do |subspan|\n # Do subspan stuff...\n end\n # Do stuff...\nend\n```\n\n### #kind\n\n def kind() -\u003e Google::Cloud::Trace::SpanKind\n\nThe kind of this span. \n**Returns**\n\n- ([Google::Cloud::Trace::SpanKind](./Google-Cloud-Trace-SpanKind))\n\n### #kind=\n\n def kind=(value) -\u003e Google::Cloud::Trace::SpanKind\n\nThe kind of this span. \n**Parameter**\n\n- **value** ([Google::Cloud::Trace::SpanKind](./Google-Cloud-Trace-SpanKind)) \n**Returns**\n\n- ([Google::Cloud::Trace::SpanKind](./Google-Cloud-Trace-SpanKind))\n\n### #labels\n\n def labels() -\u003e Hash{String =\u003e String}\n\nThe properties of this span. \n**Returns**\n\n- (Hash{String =\\\u003e String})\n\n### #move_under\n\n def move_under(new_parent)\n\nMoves this span under a new parent, which must be part of the same\ntrace. The entire tree under this span moves with it. \n**Parameter**\n\n- **new_parent** ([Google::Cloud::Trace::Span](./Google-Cloud-Trace-Span)) --- The new parent.\n**Example** \n\n```ruby\nrequire \"google/cloud/trace\"\n\ntrace_record = Google::Cloud::Trace::TraceRecord.new \"my-project\"\nroot1 = trace_record.create_span \"root_span_1\"\nroot2 = trace_record.create_span \"root_span_2\"\nsubspan = root1.create_span \"subspan\"\nsubspan.move_under root2\n```\n\n### #name\n\n def name() -\u003e String\n\nThe name of this span. \n**Returns**\n\n- (String)\n\n### #name=\n\n def name=(value) -\u003e String\n\nThe name of this span. \n**Parameter**\n\n- **value** (String) \n**Returns**\n\n- (String)\n\n### #parent\n\n def parent() -\u003e Google::Cloud::Trace::Span, nil\n\nThe TraceSpan object representing this span's parent, or `nil` if\nthis span is a root span. \n**Returns**\n\n- ([Google::Cloud::Trace::Span](./Google-Cloud-Trace-Span), nil)\n\n### #parent_span_id\n\n def parent_span_id() -\u003e Integer\n\nThe ID of the parent span, as an integer that may be zero if this\nis a true root span.\n\n\n\u003cbr /\u003e\n\nNote that it is possible for a span to be \"orphaned\", that is, to be\na root span with a nonzero parent ID, indicating that parent has not\n(yet) been written. In that case, `parent` will return nil, but\n`parent_span_id` will have a value. \n**Returns**\n\n- (Integer)\n\n### #span_id\n\n def span_id() -\u003e Integer\n\nThe numeric ID of this span. \n**Returns**\n\n- (Integer)\n\n### #start!\n\n def start!()\n\nSets the starting timestamp for this span to the current time.\nAsserts that the timestamp has not yet been set, and throws a\nRuntimeError if that is not the case.\nAlso ensures that all ancestor spans have already started, and\nstarts them if not.\n\n### #start_time\n\n def start_time() -\u003e Time, nil\n\nThe starting timestamp of this span in UTC, or `nil` if the\nstarting timestamp has not yet been populated. \n**Returns**\n\n- (Time, nil)\n\n### #start_time=\n\n def start_time=(value) -\u003e Time, nil\n\nThe starting timestamp of this span in UTC, or `nil` if the\nstarting timestamp has not yet been populated. \n**Parameter**\n\n- **value** (Time, nil) \n**Returns**\n\n- (Time, nil)\n\n### #to_grpc\n\n def to_grpc(default_parent_id = 0) -\u003e Google::Cloud::Trace::V1::TraceSpan\n\nConvert this Span object to an equivalent TraceSpan protobuf suitable\nfor the V1 gRPC Trace API. \n**Parameter**\n\n- **default_parent_id** (Integer) --- The parent span ID to use if the span has no parent in the trace tree. Optional; defaults to 0. \n**Returns**\n\n- (Google::Cloud::Trace::V1::TraceSpan) --- The generated protobuf.\n\n### #trace\n\n def trace() -\u003e Google::Cloud::Trace::TraceRecord\n\nThe Trace object containing this span. \n**Returns**\n\n- ([Google::Cloud::Trace::TraceRecord](./Google-Cloud-Trace-TraceRecord))\n\n### #trace_context\n\n def trace_context() -\u003e Stackdriver::Core::TraceContext\n\nReturns the trace context in effect within this span. \n**Returns**\n\n- (Stackdriver::Core::TraceContext)\n\n### #trace_id\n\n def trace_id() -\u003e String\n\nReturns the trace ID for this span. \n**Returns**\n\n- (String) --- The trace ID string."]]
