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:

Returns:



153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
 
# File 'lib/google/cloud/trace/span.rb', line 153

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.



227
228
229
230
 
# File 'lib/google/cloud/trace/span.rb', line 227

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) —

    The numeric ID of the span, or nil to generate a new random unique ID. Optional (defaults to nil).

  • kind (SpanKind) —

    The kind of span. Optional.

  • start_time (Time) —

    The starting timestamp, or nil if not yet specified. Optional (defaults to nil).

  • end_time (Time) —

    The ending timestamp, or nil if not yet specified. Optional (defaults to nil).

  • labels (Hash{String=>String}) —

    The span properties. Optional (defaults to empty).

Returns:

  • (TraceSpan) —

    The created span.



254
255
256
257
258
259
260
261
262
 
# File 'lib/google/cloud/trace/span.rb', line 254

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.



354
355
356
357
358
359
360
361
362
 
# File 'lib/google/cloud/trace/span.rb', line 354

def delete
  ensure_exists!
  @children.each(&:delete)
  parent.remove_child(self) if parent
  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.



341
342
343
344
345
346
347
348
 
# File 'lib/google/cloud/trace/span.rb', line 341

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.



326
327
328
329
330
331
332
333
 
# File 'lib/google/cloud/trace/span.rb', line 326

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

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

Standard value equality check for this object.

Parameters:

  • other (Object)

Returns:

  • (Boolean) 


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

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) 


198
199
200
 
# File 'lib/google/cloud/trace/span.rb', line 198

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.



314
315
316
317
318
 
# File 'lib/google/cloud/trace/span.rb', line 314

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) —

    The kind of span. Optional.

  • labels (Hash{String=>String}) —

    The span properties. Optional (defaults to empty).

Returns:

  • (TraceSpan) —

    The created span.



287
288
289
290
291
292
293
 
# File 'lib/google/cloud/trace/span.rb', line 287

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:



379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
 
# File 'lib/google/cloud/trace/span.rb', line 379

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.



302
303
304
305
 
# File 'lib/google/cloud/trace/span.rb', line 302

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

#to_grpc(default_parent_id = 0) ⇒ Google::Devtools::Cloudtrace::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:



179
180
181
182
183
184
185
186
187
188
189
190
 
# File 'lib/google/cloud/trace/span.rb', line 179

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::Devtools::Cloudtrace::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) 


207
208
209
210
 
# File 'lib/google/cloud/trace/span.rb', line 207

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.



217
218
219
220
 
# File 'lib/google/cloud/trace/span.rb', line 217

def trace_id
  ensure_exists!
  trace.trace_id
end