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:



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

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.



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

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-id"
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.



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

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.



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

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.



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

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.



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

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.

rubocop:disable Metrics/AbcSize

Parameters:

  • other (Object)

Returns:

  • (Boolean) 


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

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) 


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

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.



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

def finish!
  fail "Span not yet started" unless start_time
  fail "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-id"
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.



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

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-id"
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:



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

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.



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

def start!
  fail "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:



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

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) 


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

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.



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

def trace_id
  ensure_exists!
  trace.trace_id
end