Class: Google::Cloud::Trace::Span

Inherits:
Object
  • Object
show all
Defined in:
lib/google/cloud/trace/span.rb

Overview

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.

Instance Attribute Summary collapse

Class Method Summary collapse

Instance Method Summary collapse

Instance Attribute Details

#end_time ⇒ Time?

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

Returns:

  • (Time, nil) 


91
92
93
 
# File 'lib/google/cloud/trace/span.rb', line 91

def end_time
  @end_time
end

#kind ⇒ Google::Cloud::Trace::SpanKind

The kind of this span.

Returns:



68
69
70
 
# File 'lib/google/cloud/trace/span.rb', line 68

def kind
  @kind
end

#labels ⇒ Hash{String => String} (readonly)

The properties of this span.

Returns:

  • (Hash{String => String}) 


98
99
100
 
# File 'lib/google/cloud/trace/span.rb', line 98

def labels
  @labels
end

#name ⇒ String

The name of this span.

Returns:

  • (String) 


75
76
77
 
# File 'lib/google/cloud/trace/span.rb', line 75

def name
  @name
end

#parent ⇒ Google::Cloud::Trace::Span? (readonly)

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

Returns:



41
42
43
 
# File 'lib/google/cloud/trace/span.rb', line 41

def parent
  @parent
end

#parent_span_id ⇒ Integer (readonly)

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) 


61
62
63
 
# File 'lib/google/cloud/trace/span.rb', line 61

def parent_span_id
  @parent_span_id
end

#span_id ⇒ Integer (readonly)

The numeric ID of this span.

Returns:

  • (Integer) 


48
49
50
 
# File 'lib/google/cloud/trace/span.rb', line 48

def span_id
  @span_id
end

#start_time ⇒ Time?

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

Returns:

  • (Time, nil) 


83
84
85
 
# File 'lib/google/cloud/trace/span.rb', line 83

def start_time
  @start_time
end

#trace ⇒ Google::Cloud::Trace::TraceRecord (readonly)

The Trace object containing this span.

Returns:



33
34
35
 
# File 'lib/google/cloud/trace/span.rb', line 33

def trace
  @trace
end

Class Method Details

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



149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
 
# File 'lib/google/cloud/trace/span.rb', line 149

def self.from_grpc span_proto, trace
  labels = {}
  span_proto.labels.each { |k, v| labels[k] = v }
  span_kind = SpanKind.get span_proto.kind
  start_time =
    Google::Cloud::Trace::Utils.grpc_to_time span_proto.start_time
  end_time =
    Google::Cloud::Trace::Utils.grpc_to_time span_proto.end_time
  trace.create_span span_proto.name,
                    parent_span_id: span_proto.parent_span_id.to_i,
                    span_id: span_proto.span_id.to_i,
                    kind: span_kind,
                    start_time: start_time,
                    end_time: end_time,
                    labels: labels
end

Instance Method Details

#children ⇒ Array{TraceSpan}

Returns a list of children of this span.

Returns:

  • (Array{TraceSpan}) —

    The children.



223
224
225
226
 
# File 'lib/google/cloud/trace/span.rb', line 223

def children
  ensure_exists!
  @children.dup
end

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

Examples:

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"

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.



250
251
252
253
254
255
256
257
258
 
# File 'lib/google/cloud/trace/span.rb', line 250

def create_span name, span_id: nil, kind: SpanKind::UNSPECIFIED,
                start_time: nil, end_time: nil,
                labels: {}
  ensure_exists!
  span = trace.internal_create_span self, span_id, self.span_id, name,
                                    kind, start_time, end_time, labels
  @children << span
  span
end

#delete ⇒ Object

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



350
351
352
353
354
355
356
357
358
 
# File 'lib/google/cloud/trace/span.rb', line 350

def delete
  ensure_exists!
  @children.each(&:delete)
  parent&.remove_child self
  trace.remove_span self
  @trace = nil
  @parent = nil
  self
end

#ensure_finished ⇒ Object

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.



337
338
339
340
341
342
343
344
 
# File 'lib/google/cloud/trace/span.rb', line 337

def ensure_finished
  ensure_exists!
  unless end_time
    self.end_time = ::Time.now.utc
    @children.each(&:ensure_finished)
  end
  self
end

#ensure_started ⇒ Object

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.



322
323
324
325
326
327
328
329
 
# File 'lib/google/cloud/trace/span.rb', line 322

def ensure_started
  ensure_exists!
  unless start_time
    self.start_time = ::Time.now.utc
    parent&.ensure_started
  end
  self
end

#eql?(other) ⇒ Boolean Also known as: ==

Standard value equality check for this object.

Parameters:

  • other (Object)

Returns:

  • (Boolean) 


125
126
127
128
129
130
131
132
133
134
135
136
 
# File 'lib/google/cloud/trace/span.rb', line 125

def eql? other
  other.is_a?(Google::Cloud::Trace::Span) &&
    trace.trace_context == other.trace.trace_context &&
    span_id == other.span_id &&
    parent_span_id == other.parent_span_id &&
    same_children?(other) &&
    kind == other.kind &&
    name == other.name &&
    start_time == other.start_time &&
    end_time == other.end_time &&
    labels == other.labels
end

#exists? ⇒ Boolean

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

Returns:

  • (Boolean) 


194
195
196
 
# File 'lib/google/cloud/trace/span.rb', line 194

def exists?
  !@trace.nil?
end

#finish! ⇒ Object

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.



310
311
312
313
314
 
# File 'lib/google/cloud/trace/span.rb', line 310

def finish!
  raise "Span not yet started" unless start_time
  raise "Span already finished" if end_time
  ensure_finished
end

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

Examples:

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

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.



283
284
285
286
287
288
289
 
# File 'lib/google/cloud/trace/span.rb', line 283

def in_span name, kind: SpanKind::UNSPECIFIED, labels: {}
  span = create_span name, kind: kind, labels: labels
  span.start!
  yield span
ensure
  span.finish!
end

#move_under(new_parent) ⇒ Object

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

Examples:

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

Parameters:



375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
 
# File 'lib/google/cloud/trace/span.rb', line 375

def move_under new_parent
  ensure_exists!
  ensure_no_cycle! new_parent
  if parent
    parent.remove_child self
  else
    trace.remove_root self
  end
  if new_parent
    new_parent.add_child self
    @parent_span_id = new_parent.span_id
  else
    trace.add_root self
    @parent_span_id = 0
  end
  @parent = new_parent
  self
end

#start! ⇒ Object

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.



298
299
300
301
 
# File 'lib/google/cloud/trace/span.rb', line 298

def start!
  raise "Span already started" if start_time
  ensure_started
end

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

Parameters:

  • default_parent_id (Integer) (defaults to: 0) —

    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.



175
176
177
178
179
180
181
182
183
184
185
186
 
# File 'lib/google/cloud/trace/span.rb', line 175

def to_grpc default_parent_id = 0
  start_proto = Google::Cloud::Trace::Utils.time_to_grpc start_time
  end_proto = Google::Cloud::Trace::Utils.time_to_grpc end_time
  Google::Cloud::Trace::V1::TraceSpan.new \
    span_id: span_id.to_i,
    kind: kind.to_sym,
    name: name,
    start_time: start_proto,
    end_time: end_proto,
    parent_span_id: parent_span_id || default_parent_id,
    labels: labels
end

#trace_context ⇒ Stackdriver::Core::TraceContext

Returns the trace context in effect within this span.

Returns:

  • (Stackdriver::Core::TraceContext) 


203
204
205
206
 
# File 'lib/google/cloud/trace/span.rb', line 203

def trace_context
  ensure_exists!
  trace.trace_context.with span_id: span_id
end

#trace_id ⇒ String

Returns the trace ID for this span.

Returns:

  • (String) —

    The trace ID string.



213
214
215
216
 
# File 'lib/google/cloud/trace/span.rb', line 213

def trace_id
  ensure_exists!
  trace.trace_id
end