class Google::Cloud::Trace::TraceRecord

Trace represents an entire trace record.

A trace has an ID and contains a forest of spans. The trace object methods may be used to walk or manipulate the set of spans.

@example

require "google/cloud/trace"

env = {}
trace_context = Stackdriver::Core::TraceContext.parse_rack_env env

trace = Google::Cloud::Trace::TraceRecord.new "my-project",
                                              trace_context
span = trace.create_span "root_span"
subspan = span.create_span "subspan"

trace_proto = trace.to_grpc

Attributes

project[R]

The project ID for this trace.

@return [String]

project_id[R]

The project ID for this trace.

@return [String]

trace_context[R]

The context for this trace.

@return [Stackdriver::Core::TraceContext]

Public Class Methods

find_root_span_ids(span_protos) click to toggle source

Given a list of span protobufs, find the “root” span IDs, i.e. all parent span IDs that don't correspond to actual spans in the set.

@private

# File lib/google/cloud/trace/trace_record.rb, line 302
def self.find_root_span_ids span_protos
  span_ids = ::Set.new span_protos.map(&:span_id)
  root_protos = span_protos.find_all do |sp|
    !span_ids.include? sp.parent_span_id
  end
  ::Set.new root_protos.map(&:parent_span_id)
end
from_grpc(trace_proto) click to toggle source

Create a new Trace object from a trace protobuf.

@param [Google::Cloud::Trace::V1::Trace] trace_proto The

trace protobuf from the V1 gRPC Trace API.

@return [Trace, nil] A corresponding Trace object, or `nil` if the

proto does not represent an existing trace object.
# File lib/google/cloud/trace/trace_record.rb, line 83
def self.from_grpc trace_proto
  trace_id = trace_proto.trace_id.to_s
  return nil if trace_id.empty?

  span_protos = trace_proto.spans
  parent_span_ids = find_root_span_ids span_protos

  span_id = parent_span_ids.size == 1 ? parent_span_ids.first : 0
  span_id = nil if span_id.zero?
  tc = Stackdriver::Core::TraceContext.new trace_id: trace_id,
                                           span_id: span_id
  trace = new trace_proto.project_id, tc

  until parent_span_ids.empty?
    parent_span_ids = trace.add_span_protos span_protos, parent_span_ids
  end
  trace
end
new(project_id, trace_context = nil, span_id_generator: nil) click to toggle source

Create an empty Trace object. If a trace context is provided, it is used to locate this trace within that context.

@param [String] project_id The ID of the project containing this

trace.

@param [Stackdriver::Core::TraceContext] trace_context The context

within which to locate this trace (i.e. sets the trace ID and
the context parent span, if present.) If no context is provided,
a new trace with a new trace ID is created.
# File lib/google/cloud/trace/trace_record.rb, line 54
def initialize project_id, trace_context = nil, span_id_generator: nil
  @project_id = project_id
  @trace_context = trace_context || Stackdriver::Core::TraceContext.new
  @root_spans = []
  @spans_by_id = {}
  @span_id_generator = span_id_generator || proc { rand(1..0xffffffffffffffff) }
end

Public Instance Methods

==(other)
Alias for: eql?
add_root(span) click to toggle source

Add the given span to the list of root spans.

@private

# File lib/google/cloud/trace/trace_record.rb, line 273
def add_root span
  @root_spans << span
end
add_span_protos(span_protos, parent_span_ids) click to toggle source

Given a list of span protobufs and a set of parent span IDs, add for all spans whose parent is in the set, convert the span to a `TraceSpan` object and add it into this trace. Returns the IDs of the spans added, which may be used in a subsequent call to this method. Effectively, repeated calls to this method perform a breadth-first walk of the span protos and populate the TraceRecord accordingly.

@private

# File lib/google/cloud/trace/trace_record.rb, line 321
def add_span_protos span_protos, parent_span_ids
  new_span_ids = ::Set.new
  span_protos.each do |span_proto|
    if parent_span_ids.include? span_proto.parent_span_id
      Google::Cloud::Trace::Span.from_grpc span_proto, self
      new_span_ids.add span_proto.span_id
    end
  end
  new_span_ids
end
all_spans() click to toggle source

Returns an array of all spans in this trace, not in any particular order

@return [Array{TraceSpan}]

# File lib/google/cloud/trace/trace_record.rb, line 149
def all_spans
  @spans_by_id.values
end
create_span(name, span_id: nil, parent_span_id: 0, kind: SpanKind::UNSPECIFIED, start_time: nil, end_time: nil, labels: {}) click to toggle source

Creates a new span in this trace.

@param [String] name The name of the span. @param [Integer] span_id The numeric ID of the span, or nil to

generate a new random unique ID. Optional (defaults to nil).

@param [Integer] parent_span_id The span ID of the parent span, or 0

if this should be a new root span within the context. Note that
a root span would not necessarily end up with a parent ID of 0 if
the trace context specifies a different context span ID. Optional
(defaults to 0).

@param [SpanKind] kind The kind of span. Optional. @param [Time] start_time The starting timestamp, or nil if not yet

specified. Optional (defaults to nil).

@param [Time] end_time The ending timestamp, or nil if not yet

specified. Optional (defaults to nil).

@param [Hash{String=>String}] labels The span properties. Optional

(defaults to empty).

@return [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"
# File lib/google/cloud/trace/trace_record.rb, line 189
def create_span name, span_id: nil, parent_span_id: 0,
                kind: SpanKind::UNSPECIFIED,
                start_time: nil, end_time: nil,
                labels: {}
  parent_span_id = parent_span_id.to_i
  parent_span_id = trace_context.span_id.to_i if parent_span_id.zero?
  parent_span = @spans_by_id[parent_span_id]
  if parent_span
    parent_span.create_span name,
                            span_id: span_id,
                            kind: kind,
                            start_time: start_time,
                            end_time: end_time,
                            labels: labels
  else
    internal_create_span nil, span_id, parent_span_id, name, kind,
                         start_time, end_time, labels
  end
end
eql?(other) click to toggle source

Standard value equality check for this object.

@param [Object] other Object to compare with @return [Boolean]

# File lib/google/cloud/trace/trace_record.rb, line 68
def eql? other
  other.is_a?(Google::Cloud::Trace::TraceRecord) &&
    trace_context == other.trace_context &&
    @spans_by_id == other.instance_variable_get(:@spans_by_id)
end
Also aliased as: ==
in_span(name, kind: SpanKind::UNSPECIFIED, labels: {}) { |span| ... } click to toggle source

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.

@param [String] name The name of the span. @param [SpanKind] kind The kind of span. Optional. @param [Hash{String=>String}] labels The span properties. Optional

(defaults to empty).

@return [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...
end
# File lib/google/cloud/trace/trace_record.rb, line 228
def in_span name, kind: SpanKind::UNSPECIFIED, labels: {}
  span = create_span name, kind: kind, labels: labels
  span.start!
  yield span
ensure
  span.finish!
end
internal_create_span(parent, span_id, parent_span_id, name, kind, start_time, end_time, labels) click to toggle source

Internal implementation of span creation. Ensures that a span ID has been allocated, and that the span appears in the internal indexes.

@private

# File lib/google/cloud/trace/trace_record.rb, line 242
def internal_create_span parent, span_id, parent_span_id, name, kind,
                         start_time, end_time, labels
  span_id = span_id.to_i
  parent_span_id = parent_span_id.to_i
  span_id = unique_span_id if span_id.zero?
  span = Google::Cloud::Trace::Span.new \
    self, span_id, parent_span_id, parent, name, kind,
    start_time, end_time, labels
  @root_spans << span if parent.nil?
  @spans_by_id[span_id] = span
  span
end
remove_root(span) click to toggle source

Remove the given span from the list of root spans.

@private

# File lib/google/cloud/trace/trace_record.rb, line 282
def remove_root span
  @root_spans.delete span
end
remove_span(span) click to toggle source

Remove the given span from the list of spans overall.

@private

# File lib/google/cloud/trace/trace_record.rb, line 291
def remove_span span
  @root_spans.delete span
  @spans_by_id.delete span.span_id
end
root_spans() click to toggle source

Returns an array of all root spans in this trace, not in any particular order

@return [Array{TraceSpan}]

# File lib/google/cloud/trace/trace_record.rb, line 159
def root_spans
  @root_spans.dup
end
to_grpc() click to toggle source

Convert this Trace object to an equivalent Trace protobuf suitable for the V1 gRPC Trace API.

@return [Google::Cloud::Trace::V1::Trace] The generated

protobuf.
# File lib/google/cloud/trace/trace_record.rb, line 109
def to_grpc
  span_protos = @spans_by_id.values.map do |span|
    span.to_grpc trace_context.span_id.to_i
  end
  Google::Cloud::Trace::V1::Trace.new \
    project_id: project_id,
    trace_id: trace_id,
    spans: span_protos
end
trace_id() click to toggle source

The ID string for the trace.

@return [String]

# File lib/google/cloud/trace/trace_record.rb, line 139
def trace_id
  trace_context.trace_id
end
unique_span_id() click to toggle source

Generates and returns a span ID that is unique in this trace.

@private

# File lib/google/cloud/trace/trace_record.rb, line 260
def unique_span_id
  loop do
    id = @span_id_generator.call
    return id if !@spans_by_id.include?(id) &&
                 id != trace_context.span_id.to_i
  end
end